4 ms·
Ask HN: Comments in Code. Yay or Nay?
Do we still need to maintain comments in general-purpose scripting language? Is good code code that doesn't need comments? What are the most useful comments in code that you've seen?
- danielfalbo 11mo agohttps://www.antirez.com/news/124 https://www.antirez.com/news/124
- reconnecting 11mo agoThanks! This is about C and low-level, but what about general-purpose scripting languages? Python/PHP?
- Bender 11mo ago# If you see this comment after 2008 something went wrong. rewrite this "temporary script". I give people an excuse to get rid of my temporary things.
- reconnecting 11mo agoMay I ask if you still have this comment in production?
- Bender 11mo agoI 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.
- reconnecting 11mo agoOK, do you left them only with this comment or there was more about function or how software is operating?
- Bender 11mo agoThat 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.
- eschneider 11mo agoComments 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.
- reconnecting 11mo agoThis 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 https://softwareengineering.stackexchange.com/a/377187
- JohnFen 11mo agoThat's not talking about informative comments, it's talking about commenting out code itself. That's an entirely different thing.
- reconnecting 11mo agoThanks for clarification, so there is no such opinion that comments are bad for code reading/understanding?
- JohnFen 11mo agoI have heard devs (typically on the greener side) make the argument that comments in code are bad because they need to be maintained along with the code they're commenting on. It's quite common for devs to neglect this, leading to comments that are no longer correct, and an incorrect comment is worse than no comment. The argument touches on truths, but in my opinion pretty seriously overstates the problem. Good comments tell you things like why a design decision was made, what hidden assumptions the code is relying on, etc. Things that don't often change unless refactoring is happening. The benefit of good comments is so large that, in my opinion, they are well worth this cost. The same devs are often also of the opinion that writing code in a self-documenting manner eliminates the need for comments. This is just incorrect. Good comments tell you what the code itself can't.
- JohnFen 11mo agoComments are essential. The code may tell you the "what", but you need the comments to tell you the "why".
- _0x04 11mo agoshouldn't it be described in readme/docs?
- chrism238 11mo agoStill? Why, what changed?
- petabyt 11mo agoI can't stand people who say that all code comments are bad.
- eddd-ddde 11mo agoWhat about _most_ comments are bad?