Coding Standards
Producing readable, maintainable code
Maintainability
●
●
●
●
Consistency
Consistency
Consisstency
Source code is written for humans to read. Not computers.
Want to provide as much information as possible to the next
person who reads the code – even if that person is you
Consistency, in the form of conventions, gives lots of extra
information
Maintainability
●
Coding Standards – what are they?
–
Naming conventions
●
How to name classes, variables, files etc.
–
Code Layout
● Indentation
● Comments
–
Usage of the language
●
●
Which features to avoid
Preferred methods for accomplishing tasks
Naming Conventions
●
What are they?
–
Method for selecting names for variables,
classes, parameters to functions etc.
e.g. :
ComputeTumourGrowth(OdeSystem &rTumourOdes)
{
AbstractOdeSolver *pOdeSolver = new RungeKuttaOdeSolver();
... some more code ...
pOdeSolver->Solve(rTumourOdes);
}
Code layout
●
Consistent brace style
–
braces at start of new line, 4 space indentation
if (valueToTest == comparison)
{
doTheGoodStuff();
}
else
{
doSomethingElse();
}
●
why?
–
–
Easiest to read, know where to look to find the matching
brace
Avoids problem with no brace if statement
Code layout
●
Consistent brace style
//Potentially buggy:
if (valueToTest == comparison)
doTheGoodStuff();
●
●
C++ allows if statement without braces as above
Leads to hard to spot bug when adding another statement:
if (valueToTest == comparison)
doTheGoodStuff();
someValue = 1.5; //this will always be executed
●
If you always use braces, one less bug to find
Code layout
●
Comments
–
–
–
●
Describe the intent of the programmer
Document tricky sections of the program
Provide a way of adding metadata e.g. physical
units
Aim is to Describe, rather than Duplicate:
// initalize voltage to zero
int voltage = 0.0;
int voltage = 0.0; // Transmembrane potential (mV)
Code layout
●
Comments
–
–
–
Use comments to lay out skeleton for code
Helps to solidify the algorithm in your mind
Afterwards – no need to write more comments!
// Initialise stiffness matrix
// Add boundary conditions
// Assemble linear system
// Set initial conditions in Solution vector
// Solve linear system
Code layout
●
Comments == Documentation
–
–
–
●
We want to keep the documentation in sync with the
code
Don't want to write the same thing twice
Have to write comments anyway.....
Doxygen - generates HTML / PDF / XML from code :
/** Computes the volume of a standard cone.
*
* @param baseRadius The radius of the cone base (cm)
* @param height The height of the cone (cm)
*
* @return The volume of the cone (cm^3)
*/
double ComputeConeVolume(double baseRadius, double height)
{
....
}
Usage of Language
●
C++ lets you be very very clever...
Don't be very very clever.
●
Don't do things like this :
●
struct X {
static bool f( int* p )
{
return p && 0[p] and not p[1]>>p[2];
};
};
●
Be as clear as you can, even if it takes more
lines of code
Final notes
The time you spend typing is a tiny fraction of the
time you spend coding.
Code clearly. Save time.
Drink tea and eat doughnuts.