Report R2: Coding Standards

Produce a coding standard for use in writing the PSP exercise programs. Objectives: to establish a consistent set of coding practices, to provide criteria for judging the quality of the code you produce, to facilitate LOC counting by ensuring your programs are written with a separate physical line for each logical line of code.

Table 2-5. C++ coding standard

PurposeTo guide the development of C++ programs. Prior to counting, the source files will be processed by GNU indent with default options, which will enforce many of the rules delineated below.
File contentsOne source and one header file per class. Classes which can be fully described in a header file (all inline, which could be the case for generic classes etc.) do not require a source file. Functions which are entirely self-contained (main.cpp) do not require a separate header file.
Comments (general)Comments when used should briefly describe the intent of code rather than its internal workings. Emphasis should be placed on code clarity (proper selection of names, etc.); if sections of code seem to require explanation in order to work, they should probably be restructured for simplicity.
Class commentsEach class should have a brief descriptive header, preferable one or two lines of comments preceding the class declaration. Avoid large blocks of comments, as these are difficult to maintain and can quickly get "out of synch" with the code.
Method/Function commentsEach method and function should have a single descriptive line in the class declaration briefly describing its intent (not behaviour!). Function/method comments should not include information such as parameter types, return types, etc-- these things may change, resulting in loss of sychronization between code and comments.
Block commentsBlock comments may be used with C++, but no code may exist on the same line as a block comment. They should be used to denote large commented areas and used sparingly.
Method/Function declarationReturn type will be declared on the line before the method/function declaration.
ContractsEach method/function which has operational constraints (preconditions, postconditions, etc) should be reflected in REQUIRE, ENSURE, and CHECK macros, used from the yakIcons contract.cpp package, ie REQUIRE( num_elements > 1 ). This will serve as partial documentation, in a structured manner.
IdentifiersIdentifiers should be extremely descriptive. All identifiers will be in lower case, with words separated by underscores, ie number_of_entries, rather than NumberOfEntries (applies to class names as well). Only one identifier should be declared per line.
Accessor namesAccessor names should represent the value, usually represented by a noun, ie "standard_deviation" rather than "get_standard_deviation".
Method SizeMethods should have an obvious (long switch statement, for example) or documented reason to be longer than about 35 physical LOC; this is done to ensure modularity, simplicity, and clarity. Longer methods should be refactored if possible. Run-time efficiency is a valid reason for long methods, but only after optimization.
Braces (block begin/end)Opening and closing braces will be on a separate line and indented one level. The following statements will be on a separate line and indented another level. While this expands things considerably, it adds clarity and should present few problems. This style of brace indenting applies also to class/struct declarations.

Table 2-6. Eiffel coding standard

PurposeGuide the development of Eiffel programs. Rules will be enforced by processing files through the SmallEiffel "pretty" program. Style guidelines will be taken from [Meyer97].
GeneralRules on method size, identifiers, comments, and begin/end separators are similar to C++ standards. Comments will follow Eiffel guidelines (single comment below feature name).
File contentsOne class per file. Follow standard guidelines for layout (indexing, class, feature, etc).
LoopsEiffel loops (from/until/invariant/variant/loop/end) will have each section's keyword on a separate line.
Conditionalsif...then will be on the same line. Elseifs will have their own lines.