<commit_before>This documents C coding conventions for Teem, and provides some rationale.
Feedback on how to better implement the rationale is very welcome on the
teem-users mailing list; subscribe at:
http://lists.sourceforge.net/lists/listinfo/teem-users

============ Basic code formatting
Example function:

unsigned int
nrrdSpaceOriginGet(const Nrrd *nrrd,
                   double vector[NRRD_SPACE_DIM_MAX]) {
  unsigned int sdi, ret;

  if (nrrd && vector) {
    for (sdi=0; sdi<nrrd->spaceDim; sdi++) {
      vector[sdi] = nrrd->spaceOrigin[sdi];
    }
    for (sdi=nrrd->spaceDim; sdi<NRRD_SPACE_DIM_MAX; sdi++) {
      vector[sdi] = AIR_NAN;
    }
    ret = nrrd->spaceDim;
  } else {
    ret = 0;
  }
  return ret;
}

Note:
* No tabs, ever. (why: no two editors show them the same)
* Two spaces per level of indentation
* In function definition (and only in definition), the function name
starts a new line (why: makes it trivial to use grep or ack to
identify which source file contains the function definition, as with
"ack ^nrrdLoad")
* opening brace *not* on its own line
* closing brace gets its own line, except for if/else
* braces around a branch even if there is only one statement
(why: there will likely eventually be more than one statement, even
if only for debugging)
* single blank line between function variable declaration/initialiation
and function code.  Blank lines between distinct stages of a function
computation are nice too (like a paragraph break).

Other code formatting points:

* If at all possible please keep lines to 79 characters, like the current line.
A reference for this is the following line appearing in the source headers:
  Teem: Tools to process and visualize scientific data and images             .
with a period at the end to fill out to 79 characters. The exceptions to this
are things like setting up a gageKind, or an airEnum, where long lines help
preserve logical structure in fragile things.  Some code in teem/Testing also
exceeds this line length to increase the clarity of its repetitive structure.
(why: limiting to 80 characters is a line in the sand, but it has more
historical precedent than larger values. But the 80th character ends up being
wrapped around to the next line in some displays, hence the limit at 79).

* No trailing white-space. Changes in it are easy to make, and generate only
noise in diffs (though removing it also generates confusing diffs, but it should
be the last time). Google for "trailing white space" for further info and tips.

* In header files, when using conditionals in the C pre-processor, put
spaces between the "#" (in the first column) and (for example) the
"define", so that the logical structure is clearer, e.g:
<commit_msg>tweaks<commit_after>This documents C coding conventions for Teem, and provides some rationale.
Feedback on how to better implement the rationale is very welcome on the
teem-users mailing list; subscribe at:
http://lists.sourceforge.net/lists/listinfo/teem-users

============ Basic code formatting
Example function:

unsigned int
nrrdSpaceOriginGet(const Nrrd *nrrd,
                   double vector[NRRD_SPACE_DIM_MAX]) {
  unsigned int sdi, ret;

  if (nrrd && vector) {
    for (sdi=0; sdi<nrrd->spaceDim; sdi++) {
      vector[sdi] = nrrd->spaceOrigin[sdi];
    }
    for (sdi=nrrd->spaceDim; sdi<NRRD_SPACE_DIM_MAX; sdi++) {
      vector[sdi] = AIR_NAN;
    }
    ret = nrrd->spaceDim;
  } else {
    ret = 0;
  }
  return ret;
}

Note:
* No tabs, ever. (why: no two editors show them the same)
* Two spaces per level of indentation
* In function definition (and only in definition), the function name
starts a new line (why: makes it trivial to use grep or ack to
identify which source file contains the function definition, as with
"ack ^nrrdLoad")
* opening brace *not* on its own line
* closing brace gets its own line, except for if/else
* braces around a branch even if there is only one statement
(why: there will likely eventually be more than one statement, even
if only for debugging)
* single blank line between function variable declaration/initialiation
and function code.  Blank lines between distinct stages of a function
computation are nice too (like a paragraph break).

Other code formatting points:

* If at all possible please keep lines to 79 characters, like the current line.
A reference for this is the following line appearing in the source headers:
  Teem: Tools to process and visualize scientific data and images             .
with a period at the end to fill out to 79 characters. The exceptions to this
are things like setting up a gageKind, or an airEnum, where long lines help
preserve logical structure in fragile things.  Some code in teem/Testing also
exceeds this line length to increase the clarity of its repetitive structure.
(why: limiting to 80 characters is a line in the sand, but it has more
historical precedent than larger values. But the 80th character ends up being
wrapped around to the next line in some displays, hence the limit at 79).

* No trailing white-space. Changes in it are easy to make, and generate only
noise in diffs (though removing it also generates confusing diffs, but that's
already been done). Google "trailing white space" for further info and tips.

* In header files, when using conditionals in the C pre-processor, put
spaces between the "#" (in the first column) and (for example) the
"define", so that the logical structure is clearer, e.g:

{'fraction_non_alphanumeric': 0.064297490382854, 'fraction_numerical': 0.004396409598827624, 'mean_word_length': 4.009174311926605, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 11, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '602186', 'n_tokens_mistral': 1547, 'n_tokens_neox': 1474, 'n_words': 789}