Comments are a gift to future you. When you pick up the code again after 6 months/years/however-long-in-the-future and it looks like something you've never seen before, the comments you left should be notes you need to build context around what's in the code and (sometimes more importantly) what's NOT in the code.
This is one side, and this is something that I had in mind. However, I found that there is another popular opinion (1): that in reality, commented code is harmless. The problem is that it's messy and makes it difficult to read, etc.
I retied some time ago but I would bet a few cups of coffee that hundreds of my temporary scripts, work-around eye-sores and such are still in development, performance, staging and production.
That was just an example. There are a plethora of variations in comments, only some alluding to the script being a last minute work around. Some are about dependencies so people have some troubleshooting clues to save them time in a 3am outage. Some give history and context to specific values or settings so people do not just blindly say "oh, cargo cult" and back them out. It would take all day to list all the types of comments. Most comments are JIRA issue numbers or confluence pages but those were not optional.
Comments are a gift to future you. When you pick up the code again after 6 months/years/however-long-in-the-future and it looks like something you've never seen before, the comments you left should be notes you need to build context around what's in the code and (sometimes more importantly) what's NOT in the code.
This is one side, and this is something that I had in mind. However, I found that there is another popular opinion (1): that in reality, commented code is harmless. The problem is that it's messy and makes it difficult to read, etc.
1. https://softwareengineering.stackexchange.com/a/377187
That's not talking about informative comments, it's talking about commenting out code itself. That's an entirely different thing.
Thanks for clarification, so there is no such opinion that comments are bad for code reading/understanding?
https://www.antirez.com/news/124
Thanks! This is about C and low-level, but what about general-purpose scripting languages? Python/PHP?
May I ask if you still have this comment in production?
I retied some time ago but I would bet a few cups of coffee that hundreds of my temporary scripts, work-around eye-sores and such are still in development, performance, staging and production.
OK, do you left them only with this comment or there was more about function or how software is operating?
That was just an example. There are a plethora of variations in comments, only some alluding to the script being a last minute work around. Some are about dependencies so people have some troubleshooting clues to save them time in a 3am outage. Some give history and context to specific values or settings so people do not just blindly say "oh, cargo cult" and back them out. It would take all day to list all the types of comments. Most comments are JIRA issue numbers or confluence pages but those were not optional.
Comments are essential. The code may tell you the "what", but you need the comments to tell you the "why".