Code Comments Best Practices

Ever seen anything like this?

OK, so that might be on the crazy side of things (It’s actually the winner from the International Obfuscated C Code Contest).

‍

But every developer has opened a codebase and been unable to understand the code therein. Even with best practices, style guides, and linters, developers have idiosyncratic ways of writing their code that make it difficult to understand for other devs. 

‍

The problem is code is read far more than it’s written. If you are writing code without thinking about how it can be read by the rest of your team and the dozens of potential developers who will work on the same code for years to come, you are leaving your team in jeopardy.

‍

This is where code comments come in.

What are code comments?

Code comments are lines of text you write within your code that describe what is happening with the code. They are for other developers to read, not for machines to execute, and don’t get compiled with your actual code. They act as documentation directly within the codebase.

‍

Let’s say we had a function that adds two numbers. We might add a code comment above the function to help other developers to understand the code. Here’s an example in Python:

The line starting with the ‘#’ is a code comment in Python. Here’s an example in JavaScript:

In every language some special character or characters mark out code comments. In JavaScript, code comments start with a double forward slash (//). Most programming languages follow this double forward slash notation for code comments, with Python and Ruby being the odd ones out using a #. In HTML, the tag-based markup means comments need opening and closing tags: <!-- This is a comment in HTML →.

‍

You can use code comments to:

‍

• Describe how the code works, how it interacts with other code, or how it fits into the overall codebase.
• Provide context and explanations for code that might be difficult to understand without additional information.
• Help fellow developers understand why decisions were made or why certain code was implemented.

Code Comments Best Practices

Here are six best practices for using code comments in your projects.

Make Comments Meaningful

You can think of your code comments as explaining two details to other developers: the What and the Why.

‍

The “what” is simple–you are describing the functionality of the code. This will help other developers understand how the code works and how it interacts with other parts of the program.

‍

But the “why” is often more helpful. This will help other developers understand the concepts behind the code and how it fits into the overall codebase. For example:

In this comment we not only describe the what (the first line) but why we’re using a set (the third line), and an in-built assumption to the code (second line).

Avoid Obvious Code Comments

Sometimes what the code is doing is obvious. For example:

The comment “# Multiply a by b” is redundant as the code is simple and the function name provides clarity on what the code is doing.

‍

Code comments provide additional information that is not obvious from the code itself. If your code is complex or non-intuitive, then your code comments can help your team understand what the code is doing and why.

Write Comments as You Code

Developers love to be in ‘the flow’ when they are coding–absorbed in the code and hacking towards a solution. The thought is often “I’ll come back and add comments later.” And, of course, they don’t.

‍

Even if they did, that might cause a problem. Coming back to code even a day later and trying to add comments can be difficult for complex functionality. You’ll have just forgotten all the nuances.

‍

Comments are part of the code. If you are writing code you are also writing comments.

Use Clear and Concise Language

In Python, the PEP 8 style guide recommends keeping any line of code under 79 characters.

‍

The same should be true of your code comments. Write your brief comments, with good formatting and active voice.

You can split comments over multiple lines using  multi-line comments such as  /* to start the comment and */ to end the comment in JavaScript or “”” starts a comment and “”” ends a comment in Python.

Include Reference Links When Relevant

A way to write more concise comments is to lean on something written elsewhere, in documentation, in a tutorial, even in an SO answer.

To keep the comment clear and concise you can use a URL shortener. However, shortened URLs don’t always persist, and the URL can give the future developer context itself about what they need to read.

Update Code Comments

Just as it’s easy to forget to add code comments in the first place, it’s easy to overlook code comments as you update your code. This can lead to real problems for a team and future developers. Say your comment says a function returns one type of output, but you change the function to return something else.

‍

A new developer is introduced to the codebase and needs to quickly implement your function elsewhere. They look at the code comment to understand what it’ll return and call the function in their code. It errors. They then have to work through their own code and your code to find the problem.

‍

If you update your code comments along with your code, this isn’t a problem.