The importance of using comments in code

July 20, 2019

When writing code, using comments is of great importance. Whether you work alone or in a team, comments matter. Not properly documenting your code will make you or your colleagues waste more time solving issues, or finding a way in source files.

The Where

Three key places to add your comments are:

Right at the top of your source file to describe what the purpose of that file is and explain certain logic.
Comment the functions you implemented. Add at least a description, the parameters and the logic behind the function.
If later on, you make changes to the code you have written, you should comment on why you make these changes.

The Why

When working on a project alone, adding comments will be very useful when you have to make changes to your files later on. It makes you find your way in old files or functions. And make it easier to find what you are looking for.

When working on a team you can’t code without comments. When working in each other’s files you have to be able to understand what the purpose is of each file. And you should not have to ask your colleague what every function is about. This should already be documented so you can go on and do your work.

Working in other peoples code can be a true pain in the ass sometimes. There, I said it. But when comments are added the right way, it will be easier.

The How

Here I will show you a couple of examples of how to write comments in different coding languages.

HTML: <!– This is your comment –>
CSS / JS / PHP / C# / JAVA (multi-line): /* This is your comment */
CSS / JS / PHP / C# / JAVA (single line): // This is your comment
C# XML: /// This is your comment
Python: # This is your comment