Hacker News new | ask | show | jobs
by matthiaswh 1817 days ago
The book has an entire chapter called "Choosing Names" and another titled "Comments Should Describe Things That Aren't Obvious from the Code". Yes, good naming supplants the need for many comments, but the author goes into much greater detail about when and why comments are helpful even when you have given deep consideration into naming things.
1 comments
smichel17 1817 days ago
I wish we had better tooling for showing the git blame inline like comments. I'd rather put a one line comment "read the commit log for this line" which some editor could inline or pull up quickly than litter the source with prose (but either is better than nothing).
link
nonameiguess 1816 days ago
Some code is intended to last, potentially a very long time, and has to be separable from history metadata. If for no other reason, git trees can get really big. I had a large monorepo at an old job with some code dating back to the mid 80s and it took 10 minutes to clone because of all the history. When we finally gave up on Kiln, years after its own developers abandoned it, we migrated only the code and not the history. After that, you could clone the entire repo in 10 seconds instead of 10 minutes.

They key is you want to be able to do something like that without losing crucial information. So anything that absolutely has to be there to understand what code is doing should be directly embedded in the code, that is, it needs to be a comment, not a commit message.

link
TeMPOraL 1816 days ago
Except the same belief in "self-documenting code" that makes people ignore the need for comments, also makes them ignore the need for writing proper commit messages. Git blame won't save you, if every commit message is just a one-liner like "fix foo in bar".

Viewed from the other end: commit messages are essentially comments over changesets. If you write those well, you can use the same approach to write good comments for your types, functions and modules.

See also https://news.ycombinator.com/item?id=27009308 on what I consider to be good style of commit messages (scale up or down, depending on the size of your commits).

link