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

191–200 of 238 posts

Re: On Comments in Code

#191

Post by BearfootCoder »

bombcar wrote: post #155
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…

// // Dear maintainer: // // Once you are done trying to 'optimize' this routine, // and have realized what a terrible mistake that was, // please increment the following counter as a warning // to the next guy: // // total_hours_wasted_here = 42 //

The inverse of this is also useful:

// Dear maintainer,

// The code which follows was hacked together under desperate pressure.

// It's not smart. // It's not doing anything really subtle. // It's the only thing we could get to work in the time.

// If you want to chuck it and replace it, you absolutely should.

Re: On Comments in Code

#192

Post by pydry »

kelnos wrote: post #66
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.

> _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 find the exceptions usually boil down to:

* It's not your code - I was working with some UNIX TTY code recently and the APIs are horrendous 1970s throwbacks. But they're not changing. Working with crappy APIs is where comments about the "what" shine the most. You can only go so far with abstraction/encapsulation/facades.

* You don't have time - there's an urgent bugfix you need to get out yesterday. Do you A) rewrite the architecture to make it perfectly understandable and tell the users to wait B) drop a comment in explaining what's going on.

Re: On Comments in Code

#193

Post by watt »

jdlshore wrote: post #190
watt wrote: post #184

Earlier quoted context omitted.

what is "set point"? Is it a point that is a part of some kind of set? What's "point" - is it part of some kind of coordinates? You are documenting _what_. To document _why_, you must explain why somebody would want to change the "set point" and what is the effect, and not in terms that "setA sets a", but the semantics of it. What does setting point accomplish? What are the circumstances when you want to do it? _WHY_…

You have to assume a certain amount of domain knowledge, or you end up explaining the entire universe. In this case, "set point" is a well-understood term, and its purpose is similarly well-understood. [1] Although the team may wish to document it, the place to do so is in the team glossary (or other overview documentation), not in every function that uses it. [1] http://faculty.washington.edu/brengelm/neut_zone/pg3.…

Thanks for info, I did not know it's a common industry term!

Anyway, the point I am driving is, it's more interesting to discuss _why_ would anyone change the "set point" - common scenarios and pitfalls, than just explaining the "update_set_point changes the set point".

It's nice to go into details what are the consequences and common use-cases.

Re: On Comments in Code

#194

Post by pydry »

patrick451 wrote: post #168
bccdee wrote: post #152

Earlier quoted context omitted.

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

What about the day the Mars climate orbiter was lost because one piece of code wrongly assumed that the units of figures out of the other piece of code? :)

I find that you do sometimes need symbol names that long even though it's a code smell indicating something else is up - usually scopes that are too large or insufficiently expressive types.

I view excessively long variable names as a midpoint on a journey to improving code quality on really bad code bases.

Re: On Comments in Code

#195

Post by meow112012 »

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…

not relevant: I often left comments that helped to explain my situation. One of my last comments:

> Resignation letter sent

Sometimes code is the only way to love and to talk with...

Edited: fix some typo errors

Re: On Comments in Code

#196

Post by taneq »

cush wrote: post #174
benrbray wrote: post #165

Earlier quoted context omitted.

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…

Until the code changes, then the comments are usually worse than nothing

Then you fire the coder who changed the code without updating the comments?

Re: On Comments in Code

#197

Post by benrbray »

cush wrote: post #174
benrbray wrote: post #165

Earlier quoted context omitted.

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…

Until the code changes, then the comments are usually worse than nothing

No. Comments are like a parity check. If the comments don't match the code, then you know that either:

1) The comments are correct, but the code is wrong. This is a bug. 2) The comments are wrong, but the code is correct. This is equally a bug. Whoever makes the change has an obligation to describe their changes with a comment.

Code with no comments? Could be right, could be wrong, who knows?

Re: On Comments in Code

#198

Post by etripe »

teknopaul wrote: post #41
bregma wrote: post #34

I have never cursed an author for having too many comments. There are many cursed developers out there after my long career.

You never lived through auto-javadoc?

Ah, the awesome flavour of Markov chain nonsense that is auto-generated docs. I think the existence of this phenomenon shows the danger of strictly adhering to policy that was written by someone who never suffers its effects.

Re: On Comments in Code

#199

Post by citrin_ru »

I come to a conclusion that the main reason why some programmers argue against comments is just laziness. Writing comments requires an effort. Being smart they can find multiple reasons why their don't have to do this.

Of course it is possible to intentionally create a harmful comment, but if you trying to write a useful comment it is likely will be useful for most readers. In my career there was a lot of situations when a small comment would have saved me time - I've spend many minutes and even hours to discover something a code author knew but was too lazy to put into comments. I don't remember a single case when I suffered from an outdated/incorrect comment (though in this discussion such situations are mentioned).

Re: On Comments in Code

#200

Post by _old_dude_ »

slavik81 wrote: post #185
_old_dude_ wrote: post #89

Earlier quoted context omitted.

In a compiled language, this is true for a local variable in general, it costs nothing because the compiler uses a register for it (or at worst spill it on stack but the stack frame size is reserved once for all stack allocated variables when the function is called). The story is different, if the variable is captured by a closure/lambda, the current stack frame or part of it may be allocated on heap, leading to perf…

> the stack frame size is reserved once for all stack allocated variables when the function is called Is there somewhere that's documented for LLVM? That's my expectation of what the final compiler output should be, but I read that the IR allocates every variable dynamically, and then they optimize away whatever they can. I haven't been able to figure out how or where it's guaranteed that all allocations will be coal…

I don't know LLVM well enough, but you can play with godbolt

By example, with https://godbolt.org/z/9Kv7oo9oK you can see that values goes into registers (and that thank to 'lea' there is not many registers used).

And if you remove the option -O2, values are spilled on stack.

Post reply on HN