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.

Code Conventions

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.

This post was originally published in our partner blog by the SCM-Manager Universe Team.

Comments

No Comments

Related Posts

Mutation Testing with Pitest

Author
  • Philipp Czora
Published

Unit tests can be useful for ensuring code quality and correctness. Not every unit test makes sense, however, and bugs often manage to escape detection by unit tests. How can test quality be increased so that programming errors are detected earlier and more reliably?

A Groovy DSL for the Creation of Test Data using JPA

Author
  • Daniel Behrwind
Published

With the automated integrative testing of software that works with a complex JPA data model, it is invariably the case that sooner or later, one will face the question of how it is possible to create semantically meaningful test data without great cost. This article shows how Groovy can be used in order to define a Domain Specific Language (DSL) that enables test data to be defined so that it is easily readable, modular and separate from the actual test code.ieren.

Jenkins Pipeline plugin: code completion in IntelliJ

Author
  • Johannes Schnatterer
Published

The Pipeline plugin (formerly Workflow plugin) for Jenkins revolutionises working with Jenkins by allowing for the creation of build jobs as code. As a result, build pipelines can be put under version control, become reusable,testable and more easily readable, among other things, as something “put together with mouse clicks”.

Static code analysis with SonarQube

Author
  • Josha von Gizycki
Published

This article describes which key figures can be collected by a static analysis and how these can be interpreted. The main focus is on technical debt and complexity.