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