Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

On Comments in Code

henrikwarne.com

Post reply on HN
Print view View original

111–120 of 238 posts

Re: On Comments in Code

#111

Post by fdr »

I often weigh the value of comments -- I used to write more, now I write fewer -- by weighing odds of utility against decay into misinformation. Comments conveying something of high utility that is fundamental to the program and unlikely to change make the cut.

I save most of my remarks for commit messages, which are understood to be contemporaneous. This method requires the average commit message quality be high, otherwise, people are unlikely to think to run blame on the file, even though most text editors can do so effortlessly.

Re: On Comments in Code

#112

Post by Hasnep »

ratww wrote: post #96
crazygringo wrote: post #65

Another use for comments: to document the strategies you tried and why they failed. In other words not just the "why" but the "why not". Many times I've gone back to code I'd written previously, it seemed overly complicated, I replaced it with a simpler version... that failed... that reminded me that was what I'd tried originally and then replaced it with the more complicated version for a good reason. So now I have…

I also do this with optimisations, when I work on low-level code: If I come up with an inefficient algorithm that's short and readable, I tend to optimise it to something better but leave the reference implementation inside a code block. (This goes without saying, but: I don't leave "commented code", but code inside comment, generally formatted with Markdown)

Is there a reason you don't leave a comment with the commit hash of the change instead?

Re: On Comments in Code

#113

Post by Nullabillity »

ratww wrote: post #96
crazygringo wrote: post #65

Another use for comments: to document the strategies you tried and why they failed. In other words not just the "why" but the "why not". Many times I've gone back to code I'd written previously, it seemed overly complicated, I replaced it with a simpler version... that failed... that reminded me that was what I'd tried originally and then replaced it with the more complicated version for a good reason. So now I have…

I also do this with optimisations, when I work on low-level code: If I come up with an inefficient algorithm that's short and readable, I tend to optimise it to something better but leave the reference implementation inside a code block. (This goes without saying, but: I don't leave "commented code", but code inside comment, generally formatted with Markdown)

Sounds like a good use case for property testing!

Re: On Comments in Code

#114

Post by bentcorner »

simonw wrote: post #74
crazygringo wrote: post #65

Another use for comments: to document the strategies you tried and why they failed. In other words not just the "why" but the "why not". Many times I've gone back to code I'd written previously, it seemed overly complicated, I replaced it with a simpler version... that failed... that reminded me that was what I'd tried originally and then replaced it with the more complicated version for a good reason. So now I have…

I love having commentary like that around, but I prefer to keep it in either the commit message or (more frequently) in the issue thread linked to from the commit. That way I can use as much space as I like for it and the timestamps make it clear that it's historical commentary, not a description of how the code works right now.

One caveat with this method is that your source control system evolves and things get archived. Code is around forever but everything around it may change.

10 or 20 years from now your code may still be running, the issue system or the git commit log may not be.

Re: On Comments in Code

#115

Post by _bramses »

ElijahLynn wrote: post #3

The author touches on this a bit but I want to state this really simply: Codes needs "why" comments, not "what" comments. The "what" can be done by self-documenting code, _most_ of the time. You still need to write "what" comments sometimes, don't rule it out completely. And you routinely need to write "why" comments, self-documenting code will never provide the context of "why". Write more "why" comments.

Wanna jump in here and say I'm working on this exact problem using GPT-3. The results when added to other dev tools have been really inspiring, and I'm learning how flexible comments can be when addressing the "why"[1] instead of just the "how".

[1]https://replit.com/@bramses/stenography-carbon-bot#index.js

Re: On Comments in Code

#116

Post by neolog »

simonw wrote: post #74
crazygringo wrote: post #65

Another use for comments: to document the strategies you tried and why they failed. In other words not just the "why" but the "why not". Many times I've gone back to code I'd written previously, it seemed overly complicated, I replaced it with a simpler version... that failed... that reminded me that was what I'd tried originally and then replaced it with the more complicated version for a good reason. So now I have…

I love having commentary like that around, but I prefer to keep it in either the commit message or (more frequently) in the issue thread linked to from the commit. That way I can use as much space as I like for it and the timestamps make it clear that it's historical commentary, not a description of how the code works right now.

Some people advocate putting lots of stuff into commit messages, which makes me think I'm missing something -- commit messages are much less visible/accessible than comments in my workflow, so I don't expect my commit message to be seen.

Do you always read the whole git history of a file before editing it? What interface do you use for that?

Re: On Comments in Code

#117

Post by k__ »

Half-OT:

What happened to literate programming?

Back in the CoffeeScript days, it's creator adopted a literate programming format, which was basically Markdown with code blocks being CoffeeScript.

He talked about that as the future of programming. Whelp, CoffeeScript got killed off by ES2015 and the file format never caught on.

I know the concept of literate programming does come from Knuth, but I first heard about it with CoffeeScript.

Why did this never catch on?

Re: On Comments in Code

#118

Post by iblaine »

> Every time I come back to those parts of the program, I am happy I made the effort to add a comment – they have been very helpful!

Exactly. Rarely hear someone say there are too many comments in this code! And feel free to not stop at the docstrings. Nested loops, obfuscated 1 liners, business logic that required a cross functional meeting to understand, are all valid reasons to be generous with comments.

Re: On Comments in Code

#120

Post by simonw »

neolog wrote: post #116
simonw wrote: post #74

Earlier quoted context omitted.

I love having commentary like that around, but I prefer to keep it in either the commit message or (more frequently) in the issue thread linked to from the commit. That way I can use as much space as I like for it and the timestamps make it clear that it's historical commentary, not a description of how the code works right now.

Some people advocate putting lots of stuff into commit messages, which makes me think I'm missing something -- commit messages are much less visible/accessible than comments in my workflow, so I don't expect my commit message to be seen. Do you always read the whole git history of a file before editing it? What interface do you use for that?

The GitHub web interface, specifically the "blame" view for a file.
Post reply on HN