How to Write Clean Code

Underestimated by most writing readable and well structured code is one of the most important tools that will allow you to increase your efficiency and productivity when coding.

Why even bother?

You will have to program in pretty much every semester from now on. Having a good programming style will save you hours of work if you choose a programming style that allows for readability, quick debugging and easy adaptation.

The Basics

Variable Naming

Choose your variable name as descriptive as possible while still remaining short. Use lower camelcase when combining multiple words in one variable name. The first letter of the variable name should be in lower case.

Comments

You should use top-of-method comments to make your code easier to understand and also as a reality check if you understand what your method should do. Side comments may also be used occasionally for hard to understand statement in your code.

Indentation

Even though auto formatting exists I am often surprised that I still see code submissions which are incorrectly indented. You should indent code inside a block (including nested blocks) using the tab (or four spaces) key on your keyboard.

Methods

Use methods to make your code more readable by replacing entire walls of code by multiple methods which names tell the reader what they do. This will enhance your debugging and coding in general. Remember that in the end the "reader" will you a lot of times.

Variable Naming

Enhancing code using Variables

Naming your variable in a way that allows to directly understand their purpose goes a long way. It allows to more quickly keep track of what which variable does in a given code and we avoid confusion very common with single letter variable naming.

It is important however that single letter variable naming have their place in programming. The size of an array can be represented using a variable with name 'n', the dimensions of an array could be 'n' and 'm' and inputs to algorithms like the euclidean algorithm should use variable names as seen in mathematics.

As important as these use cases of single letter variable names are, most variable names should be more descriptive than that. Take this seriously and name your variables in a descriptive way starting with the first programming exercises. The same goes for method names. To the left you can see an example of what impact good naming for variables and methods can have.

Comments

More is not Better

A common problem with good programming style is that many advocates of good programming style exaggerate what good programming style is and fill lines with comments and spend too much time on unimportant details. We will not do this. Instead we will focus only on the important things.

Less text is sometimes better. Do not crowd your code with unnecessary comments. Keeping code compact is not necessarily a bad thing. Your goal should be to write compact code which is structured in a way that removes the need for any comments between the lines. One can see this when looking at the two code examples to the left where the first one contains more comments than the second one but is harder to read and understand.

How to write Comments

You should mainly write comments on top of each method you add to your code. Personally I recommend writing the top-of-method comment before implementing the method as it helps you understanding what exactly you want to implement. The explanation should be short and concise.

If necessary we can add comments next to a line of code. Comments on top of lines of code (besides top-of-method comments) interrupt the reading flow and stretch code making it harder to keep track of the entire code. Use side comments when you feel that certain lines of code are hard to understand.

On the bottom image to the left you can see how side comments should be used. They are intended to be used when once cannot find a way to make a line of code easier to understand as the underlying functionality it implements is complex.

Methods

How to use Methods to Enhance your Code

More code means more trouble when it comes to finding errors. Splitting large pieces of code into multiple methods will allow you to isolate parts of your code and observe each part in isolation. It also removes the need to consider each line of code when attempting to find a mistake in your code.

As a rule of thumb we make one method for each part of code that serves a different function. In the code to the left one struggles to understand what the code does. If we were to split the code into parts and defining a method for each of these parts then, with appropriate method names, we could quickly understand what the code does. This comes in addition to the above mentioned benefits.

Why Methods are so Important

Methods themselves should be short and concise and not contain too much code. Having many methods in the code is not a problem though as we can simply collapse them in our programming environment which will allow us to only see their declarations.

This is one of the things you might not recognise the usefulness at the beginning of the programming exercises. However exam programming exercises are complex and require you to implement many things in one exercise, splitting each of these required functionalities into one method allows you to conquer the exercise piece by piece.

To the left you can see the transformed method from above and one of the methods it internally uses. We are tasked to do four things and we implemented a method for each of these. This allowed us to finish one subtask after the other instead of having to consider code from one subtask in another subtask.

This practice will pop up almost everywhere so adapting it now is a good idea. You will also get much quicker and more efficient at doing so once you practice your programming skills while applying the things you learn in this section.

Local Variables

Repeated computations

Whenever we have computations we do many times in the same code segment we are making our code slower by having Java recompute the result every single time. We also unnecessarily crowd code and make it less readable due to the many operations everywhere. Replacing these computations with a descriptive variable name can have a big impact on the readability of code.

Whenever you are typing out similar computations multiple times ask yourself what they are doing and then just introduce a new local variable in the method which stores the result of said computation and is named after the purpose of the computation. This will also reduce the need to change every single appearance of the computation in case you have an off by one error in your code or you need to adapt the computation in any way as you could simply just change the value of the variable.

Local Variables

You should use local variables whenever you have the chance to do so. This especially apply to programming exercises where you have to work with a given data structure as there you might have objects with given names, e.g. nodes, that you have to iterate over. Naming the next node "nextNode" will already allow you to much more quickly spot mistakes in your code or make changes to it without having to restructure the entire code.

This is something that greatly my own capabilities when it comes to programming once I started to implement this into my programming in the first weeks of the first semester.

Spacing

Spacing to allow for quick recognition

Your brain is very good at pattern matching so you should use this ability to your advantage when it comes to writing code. One of the most important places for this when differentiating between function calls and other statements that use parentheses. It is considered good practice to have no spacing between parentheses and the function name when calling a function and to add a space in all other cases.

We should also add a space between two brackets of different type, e.g. between parentheses and curly brackets. One should also add spacing between operators and operands. Code should be compact but this only in applicable to a certain degree. Use spacing and instead write methods and variable names to remove the need for comments in between lines of code.