For the most part, programming languages are remarkably precise. Even the smallest deviation from the norms of the language can result in some serious syntax and contextual errors.
This isn’t as much of an issue with modern languages, as some are designed to be both written and read like regular English. This includes languages such as COBOL, AppleScript, Inform and more. However, some of the older languages can be incredibly complex to translate just by looking at active code.
There is one component that makes reading code more bearable, particularly in smaller segments. As you might have guessed, it has to do with comments, also referred to as “commenting out” code.
Comments — often denoted by a specific tag or symbol — are not read by the development environment or finished application. Instead, they exist only to guide someone reading through the active code.
For example, you might include a comment that explains what a snippet is used for, describing the name of an object and its parameters and what it does. Front-end IT professionals also use a similar strategy when working on projects that involve multiple sets of eyes.
Being able to rely on a consistent, common language ensures that, regardless of background or expertise, anyone looking at your project can follow what you are doing.
The Ideas Behind Commenting
Comments are written differently across languages. The way in which you designate a comment is always going to differ from language to language, but the concept behind using them — and writing them — is always the same.
As a general rule of thumb, you always want to include comments you cannot live without. If, for instance, a segment of code or what it does is obvious and would be to any coder, there’s no need to comment. That doesn’t mean you shouldn’t comment, mind you, it just means the best comments are those that are absolutely necessary.
This keeps the resulting syntax clean and efficient. More importantly, it’s much easier to read, especially at a quick glance.
But this is the bare minimum — the absolute basics, if you will. There are many other underlying reasons why you should include comments and common language in your code.
1. They Foster Collaboration
Software and applications are more commonly a collaborative effort between a large team of programmers.
Even if there’s only one person working on a project, they’ll often have other coders review their work for errors and support. By nature, comments help foster collaboration and simplify the entire process. We’ll get into why over the next few points, but for now just understand they are often used to provide context or detail to other team members or readers.
In some rare cases, they are even used to denote instructions or pressure points for the end user, such as explanations included in a config or ini file.
2. They Provide Greater Context
Have you ever walked away from a project even for a short break and forgotten where you were or what you were doing? It happens even to the best of us, and while you’re programming it becomes expected. That’s exactly why it’s best practice to include comments, not just for others but yourself too.
Comments provide the greater context and details you need to follow previous work. They may explain:
- Why you used a particular method
- What a segment of code is used for
- Problems you’ve run into during the project
3. They Are Used to Explain Methods
Coding is still largely a creative process, despite the fact that modern programming languages have common ground. Just as a graphic artist or writer would include their personality in their work, so do programmers.
One particular coder may prefer an unorthodox method that is easier and works better for them. Another may stick to industry standards in a strict manner, never deviating from the norm.
Whatever the case, comments can be used to briefly explain methods and personality of the creator. You may, for example, say why you used an uncommon method or strategy as opposed to something conventional. Other coders who have to work with your code can look at this and immediately know why methods were used and who implemented them.
This also gives them more hints as to whether or not the resulting code needs to be optimized further or whether they can trust something as-is. In an ideal world every coder would be amazing at what they do, but sadly that’s not always the case.
4. They Create a History
When updating software and releasing new versions, developers will often include something called update or patch notes. Usually, this is formatted for the end user to give them some idea of what content was changed or updated. On the syntax side of the equation, comments can be used to provide a more detailed history and portrait of updates.
Developers who come into work on a project later — or team members —can scan a wall of code and see where and when you made revisions and what they do. This also helps improve the bug and patch processes. If you add something that breaks the software, for instance, you can quickly locate it and remove it later on.
5. They Improve Reading Speeds
Modern languages are more reminiscent of conventional language, but that’s not always the case. This can make it incredibly difficult for anyone to read code and discern what’s happening behind the scenes. Even the most experienced and skilled coders can have trouble reading syntax, especially when it’s written differently than they’re used to or by someone they’re not used to working with.
Comments make reading code much faster and more efficient. You can skim through syntax and still have a clear understanding of what’s happening, without reading every single character or line. When you work with hundreds of thousands of lines of code, speed is important.
6. They Force Segmentation
Like writing a novel, article, or report, code must be segmented into smaller parts, broken up by sections, chapters, headings, or, in the coding world, objects. In other words, your code shouldn’t look like a gigantic, endless waterfall of text and characters. Instead, it should be broken up into smaller sections much easier to consume and work with.
Because of how comments work, providing context and greater detail, they often force you to segment your code. This makes it easier for teammates to see what and how something is used, and where you made revisions, updates or amendments.
It’s easy to fall into the habit of writing endless streams of code, especially when you merge work from multiple team members into one document. Comments force you to divide and partition your work so it’s much easier to collaborate with and read.