The Code Whisperer

I assume you’re creating coding standards where none exist for the company or development team. These are general tips and not aimed at a specific programming language.

Our aim in having coding standards is making code easier to understand and therefore cheaper to maintain. The document should be compact and only contain rules that will be applied at a code review. Anything else needs to be in an architectural, guidelines, procedures or specification document.

Coding standards are often used to prevent coding horrors and promote best practises, but to be honest these shouldn’t be necessary. If you have coders that are happy sprinkling their work with GOTO statements I would advise some retraining rather than enforcing standards. Standards documents are often littered with rules such as no method longer than a page, often because it’s been added in a standards document way back in the past or has been found on the Internet. Generally programmers will naturally follow these sorts of design guidelines, but taking this example, there are times when a long method is the best solution.

Best practises should be a team presentation and discussion, and if they need documenting put in the guidelines document rather than in with standards.

Rules surrounding user interface are slightly tricky to position. For some developments they could be placed in the coding standards, but for development teams with different products there may need to be one per product. I would always advise to have user interface design rules in a separate document.

Creating standards from scratch can be an uphill struggle. Here are some techniques that have worked for me over the years:

• Remember the standards can be changed, they don’t have to be perfect first time, so don’t spend too long creating them. However take into account the effect of changing existing standards below
• If you have existing standards from another development then use these as a starting point
• You may require general standards and then specific standards for each language used
• You need to get the right number and balance of people deciding the standards, so create a small standards committee of responsible and mature developers that will be able to agree rather than argue. It’s best to have an odd number of people so that a vote is always decisive
• Once complete issue the standards to the rest of the team, if possible with a short presentation. It’s absolutely crucial to get buy in from the rest of the team for the standards to benefit the development work
• Make it clear to the development team that the published standards are to be adhered to, but they are flexible and can be changed. Put into place a process where changes can be suggested and either accepted or declined by the standards committee. If declined make sure there is a good reason, which is communicated back to the person requesting the change. Remember people don’t like to be ignored, so feedback is crucial
• Wherever possible explain why a rule has been applied. This is less important for, say, variable prefixes, but vital if the standard prevents the use of certain parts of a programming language. This stops the document becoming a rule book, but instead a source of information. There may be occasions where the standards committee just doesn’t like an aspect of a programming language. If this is the case, and there is validity in including the rule, just say so

Without going into the semantics of programming languages and IDEs, here are topics that the standards should cover. Remember it’s not what you decide so much as everyone knowing. With coding standards and procedures (a future blog topic) any developer should be able to jump right in and add to a project.

• Naming standards for constants, variables, class names and methods
• Comment block template for files, classes and methods
• Comments for code changes. If you need to merge code changes between code streams or need to review a change made, this will prove invaluable. From experience this needs to include the full date of change, the name of the developer, a reference to the bug or enhancement (i.e. the unique number in the bug tracking tool) a description of the change. The start and end of the changed block of code should be marked
• Requirements for removal of code - is it deleted or commented out?
• If appropriate for the IDE the number of spaces for indentation. Sounds like a small point, but I’ve seen people struggle unnecessarily trying to amend or merge code where the indentation isn’t right.
• Location of compiled units may need specifying, particularly in a system that has multiple executables. For COM systems where there is the concept of binary compatibility, specifying the location of the compatibility object is important
• Tracing and error handling need to be defined in the standards, although it is bordering on architecture. Consistency is important in these areas and must be adhered too. This will be different for different programming languages.

And some items to avoid putting in the standards, as they are guidelines, procedures or architecture so document them separately.

• How to access data - put it in the architectural document
• Use of the source control system - put it in the procedures manual
• How to build and/or deploy the application - put it in the procedures manual

The Effect of Changing Standards Changing existing standards should be approached with caution. I’ve seen a the effect of changing the variable prefix for a data type - total chaos. Fine if all code will be brought into line with the new standard, but if not at best you have new classes and methods using the new prefix and existing code using the old prefix. And what happens if you add new variables to the existing code; do you use the old prefix to fit in with the other variables or use the new prefix?