High-Level and Low-Level Comments
How to write high and low level comments
This post is originally posted at petran.substack.com
In this post, we will cover high and low level comments and how to write them.
This post is inspired by the book A Philosophy of Software Design
🌊 Let’s dive in
Introduction
Writing comments on code is an old controversial topic in the software community, some of the community believe it helps while others believe it is a necessary evil of poorly written code.
My opinion is that comments add a great amount of value only if are written in a proper way.
Comments can significantly reduce the cognitive load of the information needed for developers to make a change.
Thus with good comments, developers can navigate more easily through the code base.
Comments should describe things that aren’t obvious from the code
Examples of badly written comments:
// 📛 Bad comments
$skillsArray = []; // here we add the skills
// Loop through the languages array
foreach ($languages as $language) {
// code continues ...Comments should not repeat the code
Low-Level Comments
Low-level comments add precision to the code in cases such as:
- Variables declaration
- Return values
- Method arguments
These types of comments add extra information that the type and name of a variable are not capable to reveal.
// Example Low-Level Comments on PHP
// #1 example
// Resume with probability score lower that 50% consider as not acceptable
public int $isResumeProbability;
// #2 example
@return array "Contains all HTTP Request Headers needed to communicate with 3rd party services"
// #3 example
@param array $identifiers "All string unique identifiers Resumes"High-Level Comments
High-level comments help to augment the code and reveal details to help the reader understand the overall design and implementation of the code.
These type of comments are used commonly inside methods to introduce what the code is doing in a more abstract and convenient way.
// Example High-Level Comment on PHP
/**
* 3rd party service doesn't accept bulk delete operations,
* fot this reason we create a pool of HTTP requests and run them
* in parallel and reduce the execution time of multiple operations
*/
$responses = Http::pool(function (Pool $pool) use ($identifiers) {
// code continues...Conclusion
Writing good comments adds value to the code base in many ways such as increasing the Development Experience DX, reducing the regressions, reducing the navigation time on large code bases, and more.
Reference :
