Coding Standards Producing readable maintainable code Maintainability Consistency

Coding Standards Producing readable, maintainable code

Maintainability ● ● 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. : Compute. Tumour. Growth(Ode. System &r. Tumour. Odes) { Abstract. Ode. Solver *p. Ode. Solver = new Runge. Kutta. Ode. Solver(); . . . some more code. . . } p. Ode. Solver->Solve(r. Tumour. Odes);

Code layout ● Consistent brace style – braces at start of new line, 4 space indentation if (value. To. Test == comparison) { do. The. Good. Stuff(); } else { do. Something. Else(); } ● 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 (value. To. Test == comparison) do. The. Good. Stuff(); ● ● C++ allows if statement without braces as above Leads to hard to spot bug when adding another statement: if (value. To. Test == comparison) do. The. Good. Stuff(); some. Value = 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; // Transmembrane potential (m. V)

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 base. Radius The radius of the cone base (cm) * @param height The height of the cone (cm) * * @return The volume of the cone (cm^3) */ double Compute. Cone. Volume(double base. Radius, double height) {. . }

Usage of Language ● C++ lets you be very clever. . . Don't be 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$