02/03/2015
in Methods
Code Conventions
Table of Contents
80% of lifetime costs goes to maintenance and hardly any software is maintained for its whole life by the original author. Therefore it is crucial that code is written in a comprehensible manner. Code conventions help to achieve this.
What are Code Conventions?
Code conventions are guidelines for the structural quality of software. They are a set of programming specific standards, practices and methods for each aspect of code written in a language. Following those guidelines helps to improve the readability of the source code, which makes it easier to maintain software. Usually code conventions are covering the following areas:
- file organization,
- indentation,
- comments,
- declarations,
- statements,
- white space,
- naming conventions,
- programming practices,
- programming principles,
- programming rules of thumb and
- architectural best practices.
If you read the code conventions of a programming language you might think: “Why would they write that down, that’s obvious, everybody knows that!”. But if you are working in a team it is essential to stick to mutual rules and to get rid of slight differences.
How to Set Code Conventions?
A good way to get started with your own code conventions is to take existing ones and adapt them to your own needs. If you want to set code conventions for Java, you can for example start with the Sun Microsystems conventions, or the Google Java Styleguide. That’s what we did. We used those documents as a basis. Some of the guidelines we inherited without a modification, some we modified a bit and some we changed according to our requirements. Of course you can add new topics with guidelines.
The following table shows you some of the guidelines and our modifications.
| Topic | Google/Sun(Oracle) Way | Our Way |
|---|---|---|
| Variable Assignment (unchanged) | Avoid assigning several variables to the same value in a single statement. It is hard to read.Do not use the assignment operator in a place, where it can be easily confused with the equality operator.
Do not use embedded assignments in an attempt to improve run-time performance. This is the job of the compiler. Example: d = ( a = b + c ) + r; //AVOID! //should be written as a = b + c; d = a + r; |
Avoid assigning several variables to the same value in a single statement. It is hard to read.Do not use the assignment operator in a place, where it can be easily confused with the equality operator.
Do not use embedded assignments in an attempt to improve run-time performance. This is the job of the compiler. Example: d = ( a = b + c ) + r; //AVOID! //should be written as a = b + c; d = a + r; |
| Providing Access to Instance and Class Variables (slightly changed) | Don't make any instance or class variable public without good reason. Often, instance variables don't need to be explicitly set or gotten – often that happens as a side effect of method calls. | Never make any instance or class variable public. Often, instance variables don't need to be explicitly set or gotten – often that happens as a side effect of method calls. |
| Line Length (changed) | Avoid lines longer than 80 characters, since they're not handled well by many terminals and tools. | Avoid lines longer than 120 characters. Exceptions:
|
| Language (new) | Everything (source code, comments, variables, object names, ...) is written in English. |
Write down everything that could improve the collaboration of your team and if you had a discussion about something try to figure out whether it should be part of your code conventions to preempt further discussions. The code conventions should never be written in stone. (Of course you shouldn’t change them on a daily basis, because that leads to confusion.)
A good way to inherit the guidelines into daily work is by using code reviews or by using automated code analyses like Checkstyle for Java or static code analyses by SonarQube.
Hint: Code guidelines should not be written and be imposed by one person. To gain a high acceptance, a group of developers should discuss the conventions.
Conclusion
Code Conventions help you to write code that is easier to maintain and to extend by others, because it is based on the same guidelines. Therefore it is better to understand by people that never saw the code before.
The most important thing about code conventions is that you stick to them. It can be helpful to use automated or manual code reviews to implement the guidelines. Manual reviews have the advantage that on the one hand the writer of the code gets feedback and on the other hand the reviewer has to check whether the guidelines were applied, which also deepens his knowledge. Of course it takes some time until everyone adopted the conventions.
