| The Personal Software Process: an Independent Study | ||
|---|---|---|
| Prev | Chapter 2. Lesson 2: Planning and Measurement | Next |
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
| Purpose | To 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 contents | One 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 comments | Each 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 comments | Each 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 comments | Block 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 declaration | Return type will be declared on the line before the method/function declaration. |
| Contracts | Each 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. |
| Identifiers | Identifiers 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 names | Accessor names should represent the value, usually represented by a noun, ie "standard_deviation" rather than "get_standard_deviation". |
| Method Size | Methods 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
| Purpose | Guide the development of Eiffel programs. Rules will be enforced by processing files through the SmallEiffel "pretty" program. Style guidelines will be taken from [Meyer97]. |
| General | Rules 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 contents | One class per file. Follow standard guidelines for layout (indexing, class, feature, etc). |
| Loops | Eiffel loops (from/until/invariant/variant/loop/end) will have each section's keyword on a separate line. |
| Conditionals | if...then will be on the same line. Elseifs will have their own lines. |