from Hacker News

Ask HN: Is Code Commenting Outdated?

by yujian on 7/19/23, 5:52 PM with 6 comments

• by theandrewbailey on 7/19/23, 6:02 PM

  Depends on what is meant by "commenting". If it's redundant and repeats what a human would reasonably understand by reading the code itself, then yes, it's bad. If a comment is there explaining why it's being done this way (e.g., some external factor that can't be deduced from nearby code), then no, commenting is not outdated.

  Code is for machines. Comments are for humans. If one is redundant, drop the comments.

• by Rochus on 7/19/23, 6:55 PM

  > saying that code commenting is an outdated practice and code should be self commenting

  Commenting is in no way outdated; it's an essential part of "self-documenting code"; of course the comments shall not duplicate what a sufficiently skilled developer can read directly from the code, but give information about why the code is there. It also depends on the programming language in use; C can be very cryptic at times, so comments are useful; also assembler requires a lot of comments to be human comprehensible. Higher level languages need less code comments. Even Brooks himself states in "The Mythical Man Month": "I find myself being briefer in comments to an APL program, which will live on a disk, than on a PL/I one that I will store as cards.".

• by justinludwig on 7/19/23, 7:20 PM

  Comments aren't outdated. Obvious code doesn't need to be commented, and code should be written to be obvious where possible.

  But where it's not possible to write obvious code, it should have comments explaining _why_ the code is doing what it's doing. Usually this will include references to external sources like issue trackers and software-design documents, or at least to other parts of the code.

  Also, really hairy bits of code (like multi-page functions etc) often need comments just to explain what the heck it does (but in that case, it should also include an explanation of _why_ it's so hairy, and the ramifications to making changes to it).

  _The Mythical Man-Month_ is still worth a read, although many of its insights that were super hot takes 50 years ago have been pretty much adopted into the mainstream.

• by ompogUe on 7/19/23, 7:08 PM

  wrt mythical man month - it's still relevant.

  the more quoted section is about how adding devs to a late project can often make it later due to exponential communication needed.

  the part about the top architect is still relevant to me for the person who best has the whole-picture concept for making design decisions of a system. mmm seemed to me less implementing this, but having other engineers doing a lot of other tool and data support. the reddit comment sounded more about coding style, not file system layout or code flow or design patterns or anything "architectural" in my mind.

• by damnesian on 7/19/23, 6:00 PM

  I can sort of see their point. A program should be clear enough logically so commenting would almost be redundant.

  However, there are different ways of doing things within the same language- so when someone comes in later with the task of changing the code to do something else, it can be a real son of a bitch to reverse-engineer even simple scripts. So as a courtesy to other professionals in a high-pressure environment, letting others know the rationale right there in the code is a simple and very useful courtesy to your fellow humans.

• by ompogUe on 7/19/23, 6:25 PM

  We're doing hand-off with another team. Enterprise level.

  They have good docs and howtos and commit logs, but then talk through sections of code where conditions are very numerous and complex to work with. We decided recently that it would be great to have in-line comments then and there to say what it does, the why on each condition.

  My 2 cents