Having been working in a team on a large-ish project I quickly found out that we all have very different coding styles. This has provided constant headaches and frustrations throughout the project as we try to work on the same files, re-factoring each others code so it fits in with our preferred styles. Not only is this a waste of time, but it can also make it hard when using subversion to merge changes to the files, as it often thinks the file has significantly changed when really it was only the amount of white-space in the indentation.
In an effort to overcome these problems I have looked into creating some coding standards for my group at work. This article discusses my research into coding standards, including what benefits they might bring and what they should specify.
What are Coding Standards?
Coding standards (also coding conventions or coding guidelines) could be defined as follows:
Coding standards are a set of guidelines that recommend programming style, practices and methods for each aspect of program. They aim to help improve the readability of the source code and make software maintenance easier.
Why do we need Coding Standards?
As defined above, coding standards are designed to help improve the readability and maintainability of your source code. This is important because:
- 80% of the lifetime cost of a piece of software goes to maintenance
- Hardly any software is maintained for its whole life by the original author[]
Coding standards help to enforce consistency over different parts of the software when there are a team of developers working together and help make the code more predictable.
Finally it can be difficult to produce and/or read diffs and patches against source code if it does not adhere to any standards, in particular when it comes to white space and indentation.
Discussion of Specific Standards
I will now look at some of the specific coding standards that are often defined in guidelines and discuss whether what benefits they bring and how appropriate they are. They will form the decision of what I include in my first version of the coding standards for my team. This is not a complete list but should capture the main sections of a coding standards document.
Spaces Around Parenthesis
Everyone has their own style when it comes to having spaces around parenthesis. Some examples are:
if(foo)
if( foo )
if (foo)
if ( foo )
Some coding standards define where the white space is acceptable. However, I do not think it makes a significant difference to the readability of the code and so will not be specifying a standard.
The Location of Braces
As with the spaces around the parenthesis, everyone will have their own style when it comes to the location of the braces. Some editors will also be configured to place the braces in a particular location. Below are some examples of braces placement[]:
if (condition) {
doSomething(); }
if (condition) {
doSomething();
}
if (condition)
{
doSomething();
}I don’t really think the location of braces matter a great matter a great deal, so long as they are sensible and the indenting is consistent. It is not something that is worth defining a standard for, especially at the risk of upsetting people who have their own ideas on the right place to put them.
Indenting
One thing that nearly everyone does agree on is the need to indent your code. This makes the code so much more readable as you can easily see where one code block starts and finishes and if there are nested blocks.
Although it is agreed that indenting is a good thing, there are arguments about how many columns to use for indenting. Most specify between two or four columns, although it really does not matter much as long as it is consistent.
In the coding standards it might be worth defining the amount of columns to use for indenting and a reminder that it should always be used where appropriate.
Tabs vs Spaces
The issue of using tabs to create white space seems to be a contentious one. The problem is the tool you are using might be configured to use tab stops of four, where another persons might be configured to use tab stops of eight, and yet another person might use spaces. So you might have spent some time formatting your code to look nice in your editor, but when the next person opens the file it might look very ugly and difficult to read.
To avoid this issue a lot of coding standards forbid the use of tabs and only allow the use of spaces to create white space. Using only spaces ensures that the code will look the same in all editors and will also avoid problems when printing or emailing code and producing/reading diffs. It should be possible to configure your editor to use spaces instead of tabs (often under the setting of “soft tabs”).
I have certainly found the issue of tabs and spaces to be very annoying and so would suggest that there should be a guideline defined in the coding standards.
As with indenting, it is generally agreed that commenting your code is a good idea. Comments help to explain what the code is doing, which can be especially useful if it is a complex piece of code. They can also be used to highlight where some code needs later attention, using comments that start with TODO, FIXME or SMELL[].
There is a question on how many comments there should be. Some people think you can never have too much of a good thing and therefore your code should be littered with comments. Others might say that if you need a comment then the code isn’t sufficiently simple enough[].
I don’t think its worth specifying how many comments people should be writing in the coding conventions. However, it might be a good idea to include a reminder that ensures everyone is using comments where appropriate.
Function headers use comments before a function is defined that documents what it does and possibly more. A function header might be as simple as the following[]:
// This function trims right and left of the string
function trim(s)
Or it could be a bit more verbose:
// -----------------
// function trim
// input: theString = string
// returns: middle portion of theString, using the Wiki2001StringAlgorithmNotByKnuth
// assumptions: theString must be at least 3 characters long (plus terminating null)
// to avoid buffer overflow error. NotKnuthStringLibrary must be opened & initialized
// before calling this function.
// ------------------
function trim(theString) {Like comments, there are mixed feelings about the usefulness of function headers. While they can help to give you an overview of what the function does, it could also be argued that if the code is clear enough then you should be able to work out what it does.
Many languages have their own format for documenting functions in the code, such as Perl’s POD[] and Java’s Javadoc[]. This can then be extracted and formatted for output in a number of ways, such as HTML and PDF.
Depending on what you are working on function headers might need to be included with the code. However for the kind of projects my group works on it should be enough to specify one or two lines before each function to describe exactly what it does.
Naming Conventions
A naming convention defines how variables, types and functions should be named in a program. This is another contentious issue where most developers have their idea of what is the right naming convention and will not want to be told to do it in a different way.
Naming conventions might need to answer a number of questions. For example, should you use bumpy case, where you use capitalization to divide each word from the next (i.e. formatNumber) or should you use underscores (i.e. format_number). They might also use the name to identify the type of macro, for example a CONSTANT in all capitals, a Class with an initial capital and an instance in lower case. A subroutine would also be lower case and would be clear from context as its usually followed by parentheses.
A famous variable naming convention is the Hungarian Notation and is where the type of the variable is encoded into its name. There is no standard for which characters should be used as the identifier, but an example might be iSize for an integer.
Naming conventions do sound like a good idea. However, different people will have different ideas on the right way to name a type. As long as it is consistent with the names of functions already in the program then it does not really matter how it is done. Therefore, when I wrote my first version of the coding standards for the team I work in I decided not to suggest a particular naming convention.
Writing the Coding Standards
It is worth considering what the coding standards document might look like and how much detail it should go in. Some coding standards are fairly short and concise, such as the BBC’s Perl Coding Guidelines, while others are quite the opposite and provide guidelines for almost all parts of writing code, such as Adobe’s Flex SDK coding conventions.
It is also a good idea to think about the style and layout of the document. Should it be listed as bullet points or discussed in paragraphs?
The coding conventions I think got the best layout are the BBC’s coding conventions for C++ and Perl, and I wrote mine in a similar way.
Publishing and Agreeing the Coding Standards
So I now have an idea of what I want to outline in the coding standards and now need to think about the best place to publish it and getting everyone’s agreement on it. At work we have a wiki, which would make an ideal home for the coding standards as it is accessible to everyone and also editable by anyone.
Once I have published the first version of the standards it will be important to get everyone’s feedback and discuss whether they are the best practices for our group. It will also be important to ensure that everyone feels a sense of ownership for the standards, which will make people more likely to adhere to them.
Conclusion
After completing this research I feel I have a good idea of what makes good coding standards and how much depth they should go into. I have also discussed many specific standards and tried to capture a developers thoughts on them.
You can view the coding standards using the link below. It turned out to be a very short document, but that’s not necessarily a bad thing. I have purposely decided not to define specific standards where we should be able to rely on the developers common sense. Also this is only a first version of the standards and they may well grow as feedback is received.
The success of the standards will be measured by their uptake and whether people feel like they have involvement in the document, rather than just being told what is right. In a months time I will write a follow up discussing how successful the coding standards have been in my group and whether people feel it has helped to improve the consistency and quality of the code.
View the coding standards (PDF)
Links
Since I read so many articles related to coding standards it would probably be easiest to browse them on Delicious. You might also want to see the Wikipedia article.
References
.
