Link to comment - https://www.reddit.com/r/SoftwareEngineering/comments/153y4cm/comment/jslnvvc/
Extra commentary from me: I've never read the mythical man month but I've heard mixed reviews, is it worth a read?
Code is for machines. Comments are for humans. If one is redundant, drop the comments.
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.".
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.
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.
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.
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