5. Coding Standards

5.1. General Guidelines

The following are a set of ‘basic principles’, based on those recommended by Bugzilla, that are also relevant to this Developer’s Guide:

  • These guidelines exist in order to reduce bugs and make it easier to change things in the future.

  • Making it easier to change things is important because an important law of code is: All Code Will Change.

  • Code should be as simple as possible. When writing code one of the primary goals should be: ‘make it easy for other programmers to use and read your code’.

  • Readable code is more important than clever code.

  • If you’re trying to be clever instead of trying to be readable, then maybe you’re trying to make things ‘faster? But remember: don’t solve a problem before you know it exists.

    Tip

    If you don’t know (by actual, detailed tests) that your code is slow, don’t worry about making it faster. This isn’t just limited to optimization - many programmers are constantly solving problems that nobody has ever experienced. Don’t do that.

  • You cannot introduce new bugs unless you change code (obviously). This means:

    • The more code you change, the more bugs you will create. There are no ‘perfect’ programmers. Everybody makes a few mistakes now and then.

    • The number of bugs introduced by a patch is proportional to the size of the patch.

    • Hence, patches should be as small as possible, and should change only what they need to change.

  • An easy way to check if your code is readable, is to ask yourself, ‘Will another programmer understand this line instantly when they look at it? If not, that line either needs to be re-written or needs a comment. See Comments for more guidelines on applying comments.

5.2. Comments

5.2.1. XML comments

Many of the existing methods and properties in source code are missing XML documentation comments (e.g. <summary>, <param>, <returns>, <value>, etc.), or the comments are out-of-date. When adding, and whenever possible when amending code, appropriate and comprehensive XML tags and comments should be added or amended to ensure they are up-to-date and sufficiently describe the section of code. The following is a good example:

/// <summary>
/// Creates a vague date string of a specified format from start and end dates
/// expressed as days elapsed since 30/12/1899.
/// </summary>
/// <param name="startDateDays">Start date in days since 30/12/1899.</param>
/// <param name="endDateDays">End date in days since 30/12/1899.</param>
/// <param name="dateType">Two-letter date format code as generated by the GetFormat method.</param>
/// <param name="outputFormat">One of the output formats in the HLU.Date.DateType enumeration.</param>
/// <returns>A vague date string in the format specified in the dateType parameter.</returns>
public static string FromTimeSpanDays(int startDateDays, int endDateDays,
        string dateType, DateType outputFormat)

5.2.2. General comments

As well as adding and maintaining XML documents at the start of each class, method or property, additional comments should be added to sections or lines of code that may need further explanation to be understood.

Although there are almost infinite opportunities to refactor and simplify code to obviate the need for comments, explaining yourself exclusively in code has its limits. No matter how simple, concise, and clear your code may end up being, it’s impossible for code to be completely self-documenting. Comments can never be replaced by code alone.

Here are a few rules of when and why comments should be added include:

  1. Make sure you explain where and why you have changed the code to help debug potential introduced bugs. See also Comment tasks.

  2. Explain why you chose to do things one way rather than another, especially if the chosen approach is not obvious. The example below not only names the technique used, but also explains why a simpler approach was not taken:

    /* A binary search turned out to be slower than the Boyer-Moore
algorithm for the data sets of interest, thus we have used the more
complex, but faster method even though this problem does not at
first seem amenable to a string search technique. */

  3. Don’t just explain what the code is doing something but why the program is doing it. It may be obvious what the code is doing, but not why.

  4. Explain how any complex sections of code that cannot be refactored or simplified work and why.

    Tip

    This is especially important for existing code - it is safer to document what the code does (once you’ve figured it out) than refactor the code and risk introducing an error.

  5. Any algorithms (calculations, logic flows, etc.) used in the program, no matter how simple they may seem when first written, should be explained.

  6. Finally, keep in mind that what seems obvious now may not seem obvious later.

Note

Remember: Code can only tell you how the program works; comments can tell you why it works.

5.2.3. Comment tasks

Comment tasks have been added at the start of each section of code that relates to a Known Issue, Change Request or Fix. Comment tasks are comments that begin with a comment task token and should be formatted as:

// TOKEN: reference (description)

where:  `TOKEN` is one of the tokens listed below
        `reference` is a Known Issue or Change Request reference (where applicable)
        `description` is a brief summary of the comment

Visual Studio can be configured so that these comments automatically appear in the Task List window. To configure Visual Studio go to Tools –> Options…, click on the Environment list heading the left to expand the list and click on Task List. Add the following Tokens to the Token List on the right:

  • FIXED : Used to indicate where a Known Issue has been fixed

  • CHANGED : Used to indicate where changes relating to a Change Request have been applied

  • FIX : Used to indicate where a previously unknown issue (e.g. identified during coding/testing) has been fixed

  • HACK : Used to indicate when a quick ‘Hack’ has been applied to temporarily resolve a previously unknown issue

  • QUERY : Used to indicate where code (possibly relating to a Known Issue or Change Request) may need to be amended/corrected

  • TODO : Used to indicate where work relating to a change or fix remains outstanding

Where possible top & tail comment borders should be inserted around the ‘Task List’ comment and related source code to denote where the change/fix/query starts and stops. Additional ‘explanatory’ comments should also be added to explain what the amended code does, or why it was amended. For example:

//---------------------------------------------------------------------
// FIXED: KI96 (BAP Habitats)
// Enable editing of bap habitats when they are only associated
// with matrix, formation, management or complex codes (rather
// than habitat codes.
OnPropertyChanged("BapHabitatsAutoEnabled");
//---------------------------------------------------------------------

The same Comment task can be inserted in multiple locations in the source code if more than one section of code relates to the same change/fix/query. However, the ‘explanatory’ comments should be bespoke for the specifically amended code.