Alpha_1 Programmers's Manual

Alpha_1 Coding Standards Summary

• General:
  • Copy Style.
  • Avoid code duplication.
  • Make the code fit into a 79-character line.
  • Only one statement may appear on a line.

• File header comments:
  • Every file (.C, .h, .str, etc.) has one.
  • Use M-x make-c-standard-header.

• Including .h files:
  • Inludes immediately follow header comment.
  • Non-Alpha_1 files first.
  • Must include "alpha_1.h".
  • Include only what is necessary.

• Header file (.h) contents:
  • Use #ifdef...#endif framing.
  • Include any required ".h" files (except "alpha_1.h"), but only those. This means the .C file:

    #include <alpha_1.h>
    #include <any.h>
    

    compiles correctly, but not if any nested includes are removed from any.h.
  • All subroutine and variable declarations must be tagged and declared extern.

• Naming conventions:
  • Think carefully when choosing names.
  • Objects inheriting from object_type end in _obj. All other classes and typedefs end in _type. No other names should have these suffixes.
  • Constants, enumerated types, and preprocessor defined constants and macros are uppercase. Elements of an enumerated type are uppercase. All other names are completely lower case.
  • Tag everything.

• Functions:
  • All functions must declare a return type on a separate line before the function name.
  • If the function is local to a file, the static keyword appears on the same line with the return type (for both the declaration and the definition). The declaration is at the beginning of the file and is not tagged. Static function definitions should be grouped together at the end of a .C file and they are tagged.
  • If all the formal parameter declarations will fit on a single line, they may appear that way. Otherwise, they must appear one per line, indented under the first one.
  • There is no space between the function name and the open parenthesis.
  • There are spaces inside the parentheses, and after all the commas in the formal parameter list.

• Formatting:
  • Minimum indentation level is 4 spaces. Use only multiples of 4 spaces except when lining up function arguments.
  • Braces appear on a line by themselves, in line with the enclosing level, and the statements enclosed by the braces are indented.
  • An else should be aligned with the corresponding if; this includes the else if construct.
  • Subroutine calls have the same spacing conventions as function declarations: no space before the open parenthesis, spaces inside the parentheses and after all arguments.
  • Operators (for, if, new, return, etc.) should not look like function calls: a space is required after the keyword. The spaces inside the parentheses are still used.

• Comments:
  There are three allowable types of comments:
  • Function declaration/definition (use M-x make-function)

    /****************************************************************
     * TAG( function_name )
     * ...
     */
    

  • Short comments (at the end of a line or a line by themselves).

    /* Comment. (Note capitalization and periods.) */
    

  • Major comments (file headers, other longer comments )

    /* This is the comment which takes more than one line and 
     * must be put in major comment form.
     */
    

  • Every external function declaration and all function definitions must have a tagged comment. The description should only be with the function definition. Use M-x make-function for full function headers where appropriate. There is no blank line between the comment and the beginning of a function declaration or definition.
  • Use reasonably correct English. Use capital letters and periods even though you may not not have completly correct sentences.

Alpha_1 Programmer's Manual Home Page