107 lines
4.5 KiB
Plaintext
107 lines
4.5 KiB
Plaintext
Guys, in the interests of proceeding with a meaningful discussion I have decided to distill the coding standards group down even more, in fact to this email group. I have collated input from some of you into this message for further discussion "offline". We'll meet again (with the group of 7) on Feb 22 to discuss the revised "coding standards" document in its entirety rather than going through it piecemeal. I think this will lead to much more expeditious results. We will refer to our standard as the "Westwood Coding Standard". This can (and will) differ from K&R and we should not allow ourselves to get hung up on this distinction. We are building a set of rules which is contemporary and practical, it is our coding standard and we can do what we like with it. We will endeavor to limit ourselves to the bounds of reason, however. This group has enough experience to ensure that.
|
|
|
|
GOAL: We should define a rigid set of parameters for source code layout for the following reasons:
|
|
|
|
A. clarity -- esp. for someone unfamiliar with the code.
|
|
B. consistency -- structure and scope should be clear by merely
|
|
examining structure/indenting without forcing the reader to analyze the code. i.e. no structure/indent exceptions.
|
|
C. maintainability -- strive for minimal coding traps or hidden
|
|
gotchas. Since maintenance coding could be done by someone who is unfamiliar with the code, it is very important that
|
|
structure/indenting rules don't force additional burdens.
|
|
D. ease of use -- structure and brace rules should be easy to
|
|
type and edit. Programmers are generally reluctant to perform unnecessary typing and recognizing this, is a legitimate concern.
|
|
|
|
RULES:
|
|
1. Indenting should consistently indicate code structure. In other words, it should be possible to immediately detect the line that controls execution of a code block by merely scanning back until the first line of indent change. This addresses goals A, B, and C.
|
|
|
|
GOOD EXAMPLE:
|
|
switch(a) {
|
|
case X:
|
|
break;
|
|
case Y:
|
|
break;
|
|
}
|
|
|
|
BAD EXAMPLE:
|
|
switch(a) {
|
|
case X:
|
|
break;
|
|
case Y:
|
|
break;
|
|
}
|
|
|
|
|
|
2. Braces placement should tightly coupled to the controlling statement. In other words, the brace should not be distant from the "if", "else", "do", or "switch". By far the most difficult to maintain is separating the "else" from the preceding "}". The greater the distance between the "}" and the "else", the greater the obscurity of the code's structure and flow.
|
|
|
|
GOOD EXAMPLE:
|
|
if (a) {
|
|
bla;
|
|
} else {
|
|
bla;
|
|
}
|
|
|
|
BAD EXAMPLE:
|
|
if (a) {
|
|
bla;
|
|
}
|
|
...
|
|
...
|
|
...
|
|
// This code block is intimately tied to the preceding "if", // but the separation obscures this. Worse yet, depending on
|
|
// the size of the comments, the "else" may not even be visible // on the screen. This violates goals A and C.
|
|
else {
|
|
bla;
|
|
}
|
|
|
|
However,
|
|
|
|
if (a) {
|
|
statement1;
|
|
} else if (b) {
|
|
statement 2;
|
|
} else if (c) {
|
|
statement 3;
|
|
}
|
|
|
|
is preferable to:
|
|
|
|
if (a) {
|
|
statement1;
|
|
} else {
|
|
if (b) {
|
|
statement 2;
|
|
} else {
|
|
if (c) {
|
|
statement 3;
|
|
}
|
|
}
|
|
}
|
|
|
|
Even though this violates A: It is not clear because if the if statements are complicated they will consistently go off the right edge of the screen, obsucuring your view of them...
|
|
|
|
This also seems to be a slight variation of B: The scope of the if statements could all be the same. There is no inherent need to change scope, so changing scope promotes extra unneeded lines (you can't see as much code this way).
|
|
|
|
3. Code lines with the same level of indention should have minimal interdependence. In other words, it should be possible to insert lines in a block of similarly indented code with minimal to no danger of breakage. This addresses goals A, B, C, and D. The second example in rule #2 demonstrates the problem. By looking at the "if" it would appear that code could be safely added past the "}", however, this would cause an error. The programmer cannot trust the indent level in this example and is thus forced to examine the subsequent code in order to look for this trap.
|
|
|
|
4. Place the braces on the same line with the control structure that it is attached to. This cuts down on the number of code lines without obscuring the structure. Less code lines means more code is visible on the screen at any one time. This addresses goals A, C, and to some extend D. This also inherently solves rule #2.
|
|
|
|
5. Always enclose code blocks in braces after an "if", "else", "do", or "while" statement. Doing so helps with code maintenance (goal C) and makes the control structures consistently coded (goal B).
|
|
|
|
GOOD EXAMPLE:
|
|
if (a) {
|
|
bla;
|
|
}
|
|
|
|
BAD EXAMPLE:
|
|
if (a)
|
|
bla;
|
|
|
|
...or...
|
|
|
|
if (a)
|
|
if (b)
|
|
bla;
|
|
else // Confusing as to which "if" it is attached to.
|
|
bla;
|
|
|