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

141–150 of 238 posts

Re: On Comments in Code

#141

Post by klyrs »

k__ wrote: post #117

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 i…

I like notebook-style programming (e.g. Jupyter, Mathematica, etc) for this. They don't quite fit the bill, and for example, don't provide a mechanism to render into a clean library with unit tests extracted from the notebook. But I still hold out hope for a good cross-language system.

Having read some of Knuth's literate code... good god that man is brilliant, but aesthetic language design isn't his wheelhouse

Re: On Comments in Code

#143

Post by mjevans »

Hasnep wrote: post #112
ratww wrote: post #96

Earlier quoted context omitted.

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?

Some day in the distant future someone will only have a tarball of the source of the last version that worked; if they're lucky.

Save that poor sod; have your comments live in your code, not in an SCM system for your code.

Re: On Comments in Code

#144

Post by dragonwriter »

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.

> 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.

Having worked with codebases that have switched SCMs and SCM-adjacent issue management systems multiple times without retaining full history, I'd prefer to have the commentary in code even if it is also in those other places.

Re: On Comments in Code

#145

Post by gizmo686 »

pmoleri wrote: post #125
macintux wrote: post #73

Earlier quoted context omitted.

I refer to this type of problem a lot when arguing comments are useful. No amount of code can document the code that isn’t there for a reason.

Or you can write tests for every single not there case. Just bringing it up, I usually write lots more comments than tests. I also encourage my teammates to add comments. The problem is when one can't really explain why the simpler approach didn't work. That requires more research just to write the comment, but I think it pays off really quick.

> The problem is when one can't really explain why the simpler approach didn't work.

Another benifit I have found is that in studying the problem to understand why the simpler approach doesn't work, you find out that it can actually work.

Re: On Comments in Code

#146

Post by owl57 »

mjevans wrote: post #143
Hasnep wrote: post #112

Earlier quoted context omitted.

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

Some day in the distant future someone will only have a tarball of the source of the last version that worked; if they're lucky. Save that poor sod; have your comments live in your code, not in an SCM system for your code.

GPL has this idea in it: trying to define what exactly should go into that tarball. The question seems meaningful and important even for proprietary code. If some authors assume that anybody modifying their code should be able to look at git commits, that probably simply means that "the preferred form of the work for making modifications to it" is a git repo.

Re: On Comments in Code

#147

Post by twobitshifter »

crazygringo wrote: post #63

> If you wonder what the method does, or what the valid input range for a parameter is, you are better off just reading the code to see what it does. I couldn't disagree more. I was recently programming a library where some parameters could be 0 or greater, some parameters necessarily greater than 0, some parameters could be Infinity, others couldn't... Similarly, if one parameter is set to zero than another paramete…

Exactly - please do javadoc style comments. “It’s not an API” is not the way to look at it. You have to look at it as - I will not be the last person to use this code block. You don’t want to force someone else on your team or your replacement to dig into your method to figure out what the parameters are and the correct usage when they see it used somewhere. Having a javadoc pop up an illuminating description is very valuable. As the code base gets bigger you can even just look at the exported javadoc to figure out if someone (maybe you) already implemented the method you are thinking of. The part of the article rejecting javadoc sounded like it was for only ephemeral projects and not a mature code base that’s been handed down.

Re: On Comments in Code

#148

Post by astura »

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?

Not with every file but I have a question as to why something might exist or why it's implemented the way it is or it just doesn't look quite right then I'd absolutely go back and read the commit message that goes with the code - "Blame" feature works well here, I use TortoiseSVN.

Re: On Comments in Code

#149

Post by twobitshifter »

alerighi wrote: post #48
mpoteat wrote: post #10

On the contrary, I find standard JSDoc and its variants to be an excellent tool for internal documentation. With hovering support in modern editors, it allows context explanation in a very streamlined and human way. The author mentions for preconditions to just “read the code”. I consider this bad advice. If using an external library, would you rather hover over the method and see its conditions, or would you rather…

If the name of the function and the parameters are clear, documenting the code seems useless. Take this real example: /** * change the temperature set point in use by the thermostat * * @param ctx the thermostat context * @param sp the new set point in 0.1 celsius degrees * @return 0 on success, But we can change around the name of the parameters like this and use proper strict types: /** * change the temperature set…

You’re missing under what conditions an error is thrown. I used your method now I got an obscure error code. I’ll change it - whoops a different error code. Documenting it would let someone know what values of set_point are valid and what context states work/don’t.
Post reply on HN