3. Formatting

Owned by Deepa Chavali
Last updated: Jan 24, 2013Version comment
4 min read

 

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.