External Declarations

External declarations should begin in column 1. Each declaration should be on a separate line. A comment describing the role of the object being declared should be included, with the exception that a list of defined constants do not need comments if the constant names are sufficient documentation. The comments should be tabbed so that they line up underneath each other. Use the tab character (CTRL I if your terminal doesn’t have a separate key) rather than blanks. For structure and union template declarations, each element should be alone on a line with a comment describing it. The opening brace ( { ) should be on the same line as the structure tag, and the closing brace should be alone on a line in column 1, i.e.

If an external variable is initialized the equal sign should not be omitted.

Comments

Comments that describe data structures, algorithms, etc., should be in block comment form with the opening /* in column one, a * in column 2 before each line of comment text (footnote 17), and the closing */ in columns 2-3.

Note that grep ^.* will catch all block comments in the file. In some cases, block comments inside a function are appropriate, and they should be tabbed over to the same tab setting as the code that they describe. Short comments may appear on a single line indented over to the tab setting of the code that follows.

Very short comments may appear on the same line as the code they describe, but should be tabbed over far enough to separate them from the statements. If more than one short comment appears in a block of code they should all be tabbed to the same tab setting.

Share
Tweet
Share
Pin