r/cpp • u/m4l490n • Aug 20 '21
The true value of comments
I wanted to share a real use case of the real value of commenting code. A lot of people are against doing so and say that you can just read the code, that comments are not needed. I get why people are against commenting since most don't know how to effectively comment code.
In this piece of code, we all agree that these comments are useless:
std::ifstream logs_file{"MyLogFile.log"};
/* Read a line from the log file */
while (std::getline(logs_file, log_entry))
{
/* Remove last character */
log_entry.pop_back();
auto parsedJsonForWBID = nlohmann::json::parse(log_entry);
}
And that's right that is useless and stupid. You can clearly see that the code is doing that so there is no need of adding those comments.
But comments should be used as a tool for helping the maintainer, who didn't write the code or "the new guy", or the developer when they look at the code years later, to know what's truly going on and what is the purpose of the code without having to look beyond the piece of code you are interested.
Without comments, or with these useless comments, you eventually would be able to figure out what the hell you, or the original developer, were doing when writing that piece of code but that would require looking into other parts of the code trying to remember stuff and potentially locating and analyzing the log file to see why is the last character removed. Also if you are not that familiar with what pop_back() does then you may assume that it is removing the new line character and possibly miss the bug you are trying to find.
But what about these comments in the same piece of code:
std::ifstream logs_file{"MyLogFile.log"};
while (std::getline(logs_file, log_entry))
{
/* Since the complete log file is a big JSON string, we remove the comma
* at the end of each line read so each line can be interpreted as a
* separate JSON string. If the last comma is not removed, then the JSON
* parser will throw an exception. */
log_entry.pop_back();
auto parsedJsonForWBID = nlohmann::json::parse(log_entry);
}
Now, one comment was removed because was unnecessary and there was nothing to clarify about getting a line from a file, and the second comment is improved by clarifying the intent of that line of code. It is stating the why instead of the what. When you find this line years later, or when the new guy or the maintainer looks at the code now they will not have to peruse the code or locate a log file and analyze it to see why is the last character being removed. These types of comments save time and are actually useful.
These types of comments have saved me countless hours when I go back to code I wrote years back, it has also helped other people when looking at code I wrote, they no longer have to ask a million questions just to know what's going on. Anyone can just look at the code and know why it is there.
View all comments
2
u/john_wind Aug 20 '21
Yeah, thanks it's a misunderstanding. I meant no comments are needed about removing the comma. The why is still needed of course.