Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin

Page Tree
startDepth2
searchBoxtrue

 

Anchor
Formatting
Formatting
3. Formatting

Use of standard formatting makes code easier to read. The general principles for formatting various kinds of statements are as follows:

  • Use blank lines to organize statements into paragraphs and to separate logically related statements.
  • Limit the complexity of statements - break a complex statement into several simple statements if it makes the code clearer to read. This may make it easier to debug, if necessary, as well.
  • Indent to show the logical structure of your code.
3.1 Variables
  • It is preferable to declare only one variable per line in the code.
3.2 Brace {}
  • Braces should be used for all blocks. The first brace should appear on the following line, lined up with the keyword.

for (j = 0; j < MAX_NUMBER_OF_ITERATIONS; j++) { statement1; statement2; ... }
class SolarSystemBody { statement1; statement2; ... };

3.3 Parentheses ()
  • Always put ( ) around a condition.
  • Put a space between a keyword and parentheses

for (j = 0; j < MAX_NUMBER_OF_ITERATIONS; j++) { statement1; statement2; ... }

3.4 Indentation
  • Use three spaces for optimum readability and maintainability.
  • When the standard spaces indentation is unworkable, use some logical spacing.
  • When there are several variable declarations listed together, line up the variables.

int initialByteCount = MINIMUM_NUMBER_OF_BYTES; Earth theEarth; ClientProvidedAngularVelocity clientProvidedAngularVelocity; Matrix33 m;

3.5 Tab / Space
  • Do not use tabs. Use spaces, as tabs are defined differently for different editors and printers.
  • Use appropriate spacing to enhance the readability.
  • Put one space after a comma and semicolons:

exp(2, x) for (i = 0; i < n; ++i)

  • Put one space around assignment operators:

c1 = c2

  • Put space between keyword and parentheses:

if ( ) while ( )

  • Always put a space around conditional operators:

z = (a > b) ? a : b;

  • Do not put space before parentheses following function names:

z = exp(2, x)

  • Do not put spaces between unary operators and their operands:

p->m s.m a[i] a

  • Do not put space around the primary operators: ->, ., [ ]

++i-n *p &x

3.6 Blank Lines
  • Use blank lines to create paragraphs in the code or comments to make the code more understandable.
3.7 Method/Function Arguments
  • When all arguments for a function do not fit on one line, try to line up the first argument in each line.

void SomeFunction(unsigned int someCounter, double someScaleFactor, int someOtherArgument, const SolarSystemBody &solarSystemBody, int theLastArgument);

  • If the argument lists are still too long to fit on the line, you may line up the arguments with the method name instead.
3.8 If / If else
  • Indent statements one level using braces. For a single statement use of braces is optional.

if (condition) statement; else if (condition) statement; else statement;  
if (condition) { statement 1; statement 2; ... } else if (condition) { statement 1; statement 2; ... } else { statement; }

  • It is recommended to use explicit comparisons.

use
if (theFile->EndOfData() != true)
instead of
if ( ! theFile->EndOfData())

  • Always use braces for nested if statements.
3.9 Switch
  • All switch statements should have a default case, which may be merely a "fatal error" exit.
  • The default case should be last and does not require a break, but it is a good idea to put one there anyway for consistency.
  • Falling through a case statement into the next case statement shall be permitted; a comment is recommended.
  • Use the following format for switch statements: If you need to create variables put all code in a block

switch (expression) { case aaa: statement[s] break;
case bbb: // fall through
case ccc: { int v; statement[s] break; }
default: statement[s] break; }

3.10 For / While
  • Indent statements one level using braces. For a single statement use of braces is optional.

for (condition) statement;
for (condition) { statement1; statement2; ... }
while (condition) { statement[s] }

3.11 Break
  • A break statement can be used to exit an inner loop of a for, while, do, or switch statement at a logical breaking point rather than at the loop test.

while (condition) { while (condition) { if (condition) { break; } } }

3.12 Use of goto
  • Do not use goto.
3.13 Use of ?:
  • Conditional statements are fine as long as they are not too complex. 
  • Put the condition in parentheses so as to set it off from other code.

(condition) ? statement1 : statement2;
(condition) ? long statement1 : long statement2;

3.14 Return Statement
  • Multiple return statements are allowed in a function, if it makes the code more efficient.
    • For Efficiency
  • Using an expression (including a constructor call) in a return statement is more efficient than declaring a local variable and returning it (avoiding a copy-constructor and destructor call).

return Vector3((cosArgPer * cosRA - sinArgPer * sinRA * cosI), (cosArgPer * sinRA + sinArgPer * cosRA * cosI), (sinArgPer * sinI));

3.15 Maximum Characters per Line
  • Lines should generally be no more than 80 characters long for the base code and 120 characters for the GUI code.
  • This line length may be adjusted, but wrap-around should be minimized, so that the code should remain easy to read in your editor and when printed.