Writing High Quality, Understandable Code

High quality, understandable code is the key to writing an application that can be easily maintained throughout its lifespan.

Any application from large code-heavy monoliths to even the smallest micro-service can be complicated to understand for a developer new to a project. Whether the code performs multiple complex functions or has a single distinct purpose it should endeavour to be understood by any competent developer so it can be easily maintained and updated for weeks, months or even years to come.

How do I write high quality code?

There are two main camps in this; documented and self-documenting code. The question of which is best has been posed and argued over for a long time. Developers on each side of the fence use compelling arguments both for and against.

Common arguments for writing self-documenting code include:

• your code tells you exactly what it’s doing by use of variable, function/method and class names without the need for comments
• comments that exist in code are often unmaintained and can lead to misdirecting a user of the code’s purpose

Example of self-documenting code:

Developers in the documentation camp will often argue:

• lazy developers prefer “self-documenting” code to avoid having to write good documentation
• it takes longer to read code than comments, comments can give insight and understanding in a human readable form

Example of heavily documented code:

Both approaches offer some benefit to the viewer.

The documented example provides the explanation as to why something is written in a certain way, and helps a viewer who may be unfamiliar with the language or technology to better understand what is happening.

The self-documenting example provides the viewer with all the information in the code itself but assumes that the viewer is a developer with at least a basic understanding of the coding language and underlying technology.

Note: many developers often confuse the term self-documenting or clean code to mean code without comments, but this is not strictly true. In self-documenting code, comments should not exist to explain what the code is doing but rather why and only when necessary.

The Solution

The truth is even the cleanest, best structured code that follows an industry standard naming convention and coding-style will still take some time to understand and lack details of the “bigger picture” e.g. overall architecture.

The best way to write easy-to-understand code is to use a combination of both practices; here is a good example of this approach:

This code is written based on a few key principles:

Code structure & Presentation

Use a well-defined code structure and follow industry / language level naming and formatting convention. Peer review new code or changes frequently to ensure consistency i.e. have a peer proof-read your code.

Whichever standard(s) your project adopts / implements, ensure these are followed across your entire development practice.

Documentation

Use of some documentation such as JavaDoc is important but only where it’s really needed, keeping it concise and to the point i.e. no more than one or two lines. If your function requires more then it’s likely already too complicated.

Most importantly keep the documentation / comments up to date; this part is key and is the main complaint of developers who advocate purely self-documenting code.

When maintaining or migrating an existing application it is unlikely to be possible to re-write the code into a self-documenting format especially where code is old or from a legacy platform with no scope to re-write the codebase. This is where documentation is exceptionally important.

Tools

Define and share an IDE code formatter along with build tools such as Checkstyle, Findbugs and Lint (e.g. Sonarlint) that will help developers produce a consistent style and quality of code.

Summary

New code should be written in an industry standard format/structure that documents itself as much as possible and includes supporting comments where it’s not immediately obvious why a piece of code behaves the way it does.

Existing code that is being changed in some way e.g. updated or migrated to another platform should be updated to include just enough documentation (comments, JavaDoc etc) as explanation where re-writing / refactoring is not in-scope or not possible.