Emily Jiang

I am a big fan of simple and readable code. Every line of code should be as self-explanatory as possible. Every line of code should be necessary. To achieve readable and simple code, there are two aspects: format and content. Here are some tips to help you write code that is readable and simple:

Use indentation to lay out your code clearly.

Use it consistently. If you work in a project, there should be a code template. Everyone on the team should adopt the same code format. Don’t mix spaces with tabs. I always have the IDE configured to display spaces and tabs so that I can spot the mix and fix them. (Personally, I love spaces.) Choose either spaces or tabs, and stick to it.

Use meaningful variable names and method names.

The code is much easier to maintain if it is self-explanatory. With meaningful identifiers, your code can talk for itself instead of needing a separate comment line to explain what it does. Steer clear of single-letter variable names. If your variable and method names have clear meaning, you will not normally need comments to explain what your code does.

Comment your code if necessary.

If the logic is very complex, such as regex queries, etc., use documentation to explain what the code is trying to do. Once there are comments, you need to ensure they are maintained. Unmaintained comments cause confusion. If you need to warn a maintainer about something, make sure you document it and make it stand out, such as adding “WARNING” at the start of a comment. Sometimes a bug can be spotted and fixed more easily if the original author expresses their intention or puts a warning somewhere.

Don’t check in commented-out code.

Delete it to improve the readability. One of the common arguments for the commented-out code is that some day the commented-out code might be needed. The truth is that it might stay there for years, unmaintained and causing confusion. Even if one day you want to uncomment it, the code block might not compile or work as expected as the base might have changed significantly. Don’t hesitate. Just delete it.

Don’t overengineer by adding might-be-useful-in-the-future code.

If you are tasked to deliver some functionality, don’t overdo it by including additional speculative logic. Any extra code runs the risk of introducing bugs and maintenance overhead.

Avoid writing verbose code.

Aim to write fewer lines of code to achieve a task. More lines introduce more bugs. Prototype first via brainstorming to get the task done, and then polish the code. Make sure each line has a strong reason to exist. If you are a manager or architect, don’t judge your developers by how many lines of code they deliver but by how clean and readable their code is.

Learn functional programming, if you have not already.

One of the advantages of using features introduced in Java 8, such as lambdas and streams, is that these features can help to improve your code readability.

Adopt pair programming.

Pair programming is a great way for a junior developer to learn from someone who is more experienced. It is also a great way to write meaningful code, as you need to explain your choices and reasoning to the other person. A great process encourages you to write code with care instead of dumping code.

Code will have fewer bugs if it is simple and readable: code that is complex is likely to have more bugs; code that is not easily understood is likely to have more bugs. Hopefully, these tips can help you to improve your skills and your code, to deliver code that is simple and readable!