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

161–170 of 238 posts

Re: On Comments in Code

#161

Post by nineteen999 »

ravenstine wrote: post #68
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…

When I started out programming I was taught that the code should "document itself" and that comments were an anti-pattern to writing good code. It took me a few years realize how idiotic that was and deprogram myself. It's one of those things that sounds nice, but once you've moved beyond a certain level of complexity you realize how impractical it is. The fact is that "good code" is often in the eye of the beholder…

> was taught that the code should "document itself" > comments were an anti-pattern to writing good code

I've been programming in one form or another since I was 8 years old (around 38 years) and this was obviously incorrect to me back then, even though I wasn't sharing my work with anyone else, and hadn't heard this concept.

Years later I was astounded to move into a "modern" dev environment where people (developers, devops) parroted this line regularly. As you say it's nice in principle, but in reality relying on it proves to be impractical.

Re: On Comments in Code

#162

Post by neolog »

simonw wrote: post #160
neolog wrote: post #154

Earlier quoted context omitted.

That only shows the most recent commit, which is IME often not substantive, just some treewide commit like "autoformat" or "moved class into another file" or whatever. I can click on the parent commit button repeatedly until I find all the info but that's really not a good interface for exposing the history of a class.

Each line in the GitHub web blame interface has a little icon which, when you hover over it, says "View blame prior to this change" - I use that all the time.

Yeah that's the parent button I was referring to in my comment.

Re: On Comments in Code

#163

Post by retsibsi »

pjerem wrote: post #104
teknopaul wrote: post #43

Earlier quoted context omitted.

nonsense. code is intended for a computer by definition.

No. Code is intended for your teammates. Compiled machine code is for your computer. If you were addressing a machine, you would be writing 0s and 1s, because o boy do the machine know how to execute those little ons & offs.

People often insist on this point, and I still don't get it. Honestly it comes across as intentionally exaggerating a claim beyond reason, in order to make it sufficiently counterintuitive to sound clever.

The point of the program is to get the computer to perform some task; the way we get the program into the computer is to write code.

You can say we're writing code for the compiler if you want to be pedantic; or you can say we're writing code for humans too, which is a perfectly valid point. But what do you actually mean by insisting that no, the code isn't for the computer at all, it's solely for other humans? It's clearly the language we use to communicate with the computer to tell it what to do; the fact that there's a translation step (performed by the computer) between what we write and what the computer executes doesn't change that in any relevant way.

Re: On Comments in Code

#164

Post by SulphurCrested »

Sometimes code relies on some condition being true, where that condition can be reasoned about by the developer rather than at run time by the program they are writing. I don’t think such comments fall cleanly into either the “what” or “why” categories people have mentioned here – perhaps they are “how”.

In mathematical terminology, the condition may depend on some lemma or theorem the programmer proved to themselves when writing the code. (I say “lemma” and “theorem”, but this applies to any kind of complex business logic, or the state of a realtime system, etc.) For a lemma (fancy name for a small theorem), the reasoning can go inline in the code, as a comment. If it’s a theorem, a more substantial thing you proved to yourself when writing the code, it might be better put in a separate document which a comment in the code should point to.

The reasoning you used to show the code works is better off written down for those who follow than forcing them to think through the same logic again. And the act of expressing the logic in a comment will tend to flush out errors in that logic. Those are both good reasons to spend the time writing such comments, unless you don’t care about technical debt.

As a special case, runtime assertions often need a brief comment to explain why they must be true.

Re: On Comments in Code

#165

Post by benrbray »

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.

Tests are useful, but the big reason that comments are useful is that they are co-located with the relevant code. At the moment, I don't know of any tools that allow you to 1) specify which lines of code are directly relevant to a particular test case, even when the surrounding code changes and 2) see a list of test cases related to the currently highlighted line.

I'm sure it would be possible to build such a tool, but the complexity is quite substantial compared to a simple comment or two. If you really want to go the full-test-coverage route it makes a lot more sense to focus that energy on pure/immutable/statically-verified programming rather than some finicky test cases that add substantial maintenance cost to the code.

Re: On Comments in Code

#166

Post by patrick451 »

fouc wrote: post #98
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…

If you have a unit test for that piece of code then that would probably help to act as a stopgap measure against attempting to "fix" the complicated-seeming code.

I mean sort of. If the goal of leaving the a comment about the approach that didn't work is to save somebody time before they try that approach again, a regression test is essentially asking the next developer to reconstruct a broken algorithm from thin air based a test. In my opinion, that's close to impossible. So the best case scenario is they re-implement the bad approach and it fails a test. They still wasted a bunch of time that could have been prevented with a simple comment.

Re: On Comments in Code

#167

Post by truffdog »

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?

I use fugitive, which lets me pop open a blame view for code I'm looking at and trace its lineage. It's often helpful, and when the commit messages are good, very helpful.

Re: On Comments in Code

#168

Post by patrick451 »

bccdee wrote: post #152
kelnos wrote: post #66

Earlier quoted context omitted.

> _most_ of the time This is the thing that annoys me with arguments about all this. I will generally say "document the 'why' and not the 'what'; if the 'what' isn't clear from the code, fix the code to make it clear". And people will say "that's invalid because sometimes you really do need to do something clever and the 'what' needs to be documented" or whatever. And yes, that's fine! Stop taking everything people s…

I think people often lean too far in favour of "self-documenting code," and "what" comments wind up being underused. The idea of self-documenting code is that the documentation is encoded in the function and variable names, more or less. Sure, extraneous comments should usually be avoided, but frankly, sometimes a couple sentences of plain English is just clearer. I'd rather people just tell me what's going on than t…

When your coding standard enforces 80 characters, you end with a single logical statement split across many lines. This quickly approaches un-readability if you fetishize self documenting code. In my opinion, short variable and function names with a comments are often more readable that self documenting behemoths, e.g.,

double compute_angular_acceleration_in_radians_per_second_per_second(double torque_in_newtons_per_meter, double moment_of_inertia_in_kilogram_meters_meters);

vs

// Units are base unitsSI.

double compute_angular_accel(double tau, double J);

I'll take the second any day.

Re: On Comments in Code

#169

Post by dzonga »

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 use a design doc for this in the style of a append journal. I made this decision a/e/i/o/u based on this and that. the why and the why not. Then I keep appending. easy reference.

Re: On Comments in Code

#170

Post by dstick »

benrbray wrote: post #165
pmoleri wrote: post #125

Earlier quoted context omitted.

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.

Tests are useful, but the big reason that comments are useful is that they are co-located with the relevant code. At the moment, I don't know of any tools that allow you to 1) specify which lines of code are directly relevant to a particular test case, even when the surrounding code changes and 2) see a list of test cases related to the currently highlighted line. I'm sure it would be possible to build such a tool, b…

Exactly. And then the question remains: why? Why hate comments so much? I never got that
Post reply on HN