standards: Comments

1 
1 5.2 Commenting Your Work
1 ========================
1 
1 Every program should start with a comment saying briefly what it is for.
1 Example: 'fmt - filter for simple filling of text'.  This comment should
1 be at the top of the source file containing the 'main' function of the
1 program.
1 
1    Also, please write a brief comment at the start of each source file,
1 with the file name and a line or two about the overall purpose of the
1 file.
1 
1    Please write the comments in a GNU program in English, because
1 English is the one language that nearly all programmers in all countries
1 can read.  If you do not write English well, please write comments in
1 English as well as you can, then ask other people to help rewrite them.
1 If you can't write comments in English, please find someone to work with
1 you and translate your comments into English.
1 
1    Please put a comment on each function saying what the function does,
1 what sorts of arguments it gets, and what the possible values of
1 arguments mean and are used for.  It is not necessary to duplicate in
1 words the meaning of the C argument declarations, if a C type is being
1 used in its customary fashion.  If there is anything nonstandard about
1 its use (such as an argument of type 'char *' which is really the
1 address of the second character of a string, not the first), or any
1 possible values that would not work the way one would expect (such as,
1 that strings containing newlines are not guaranteed to work), be sure to
1 say so.
1 
1    Also explain the significance of the return value, if there is one.
1 
1    Please put two spaces after the end of a sentence in your comments,
1 so that the Emacs sentence commands will work.  Also, please write
1 complete sentences and capitalize the first word.  If a lower-case
1 identifier comes at the beginning of a sentence, don't capitalize it!
1 Changing the spelling makes it a different identifier.  If you don't
1 like starting a sentence with a lower case letter, write the sentence
1 differently (e.g., "The identifier lower-case is ...").
1 
1    The comment on a function is much clearer if you use the argument
1 names to speak about the argument values.  The variable name itself
1 should be lower case, but write it in upper case when you are speaking
1 about the value rather than the variable itself.  Thus, "the inode
1 number NODE_NUM" rather than "an inode".
1 
1    There is usually no purpose in restating the name of the function in
1 the comment before it, because readers can see that for themselves.
1 There might be an exception when the comment is so long that the
1 function itself would be off the bottom of the screen.
1 
1    There should be a comment on each static variable as well, like this:
1 
1      /* Nonzero means truncate lines in the display;
1         zero means continue them.  */
1      int truncate_lines;
1 
1    Every '#endif' should have a comment, except in the case of short
1 conditionals (just a few lines) that are not nested.  The comment should
1 state the condition of the conditional that is ending, _including its
1 sense_.  '#else' should have a comment describing the condition _and
1 sense_ of the code that follows.  For example:
1 
1      #ifdef foo
1        ...
1      #else /* not foo */
1        ...
1      #endif /* not foo */
1      #ifdef foo
1        ...
1      #endif /* foo */
1 
1 but, by contrast, write the comments this way for a '#ifndef':
1 
1      #ifndef foo
1        ...
1      #else /* foo */
1        ...
1      #endif /* foo */
1      #ifndef foo
1        ...
1      #endif /* not foo */
1