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

61–70 of 238 posts

Re: On Comments in Code

#61

Post by RandallBrown »

simonw wrote: post #57

I care much more about revision history than I do about comments. When I'm trying to figure out code I do it in "git blame" mode - what I'm hoping for is a single, atomic commit that links back to an issue thread. Ideally that issue thread will have all of context I need to fully understand the change. This works great in codebases that are designed to be read in that way, which is why I'm so keen on every commit com…

Definitely.

Commit messages are updated with the code automatically. Comments seem to become out of date almost immediately.

Re: On Comments in Code

#62

Post by rrose »

wongarsu wrote: post #51
rrose wrote: post #32

Earlier quoted context omitted.

it feels like this suggests a design flaw. You should probably be creating a new local `total_count` variable for each run that goes out of scope at the end of the run, rather than reusing the same variable over and over again in different contexts

// reuse counter for performance, this brings 2% speedup total_count = 0; would be a quite useful why comment, if not creating a new variable each time is intentional

sure, but reusing an integer variable is never going to bring a 2% speedup. allocating a new variable of almost any type is not going to cause any performance issues, at least if it is allocated on the stack, and if the construction of the variable is particularly expensive, resetting it probably will be too.

I would need to see a realistic example to believe that something like this would ever be a useful comment.

Re: On Comments in Code

#63

Post by crazygringo »

> 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 parameter will have no effect...

JSDoc kept the whole thing sane. "Reading the code" would take several minutes to figure out the answer in each case, which would be wasted time in my book.

JSDoc is awesome. Not every function needs it, but plenty do.

Re: On Comments in Code

#64

Post by kelnos »

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…

The worst, though, is when a comment tells you the valid input range, but it's wrong, because someone later changed the code and didn't update the comment. While this doesn't happen frequently, I've gotten bit by it enough that I will generally at least take a cursory look over the function body to verify that the comment is still correct.

I wouldn't say this makes the comment useless, but it does reduce the usefulness. And this might end up biting someone who has decided to trust the comments.

Re: On Comments in Code

#65

Post by crazygringo »

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 a new rule: every time I try a simple approach and it fails and I replace it with a more complicated one that works, I add a comment explaining the previous strategy and why it didn't work.

Hilariously, some of these have grown to several failed attempts. "Tried A library but it has a critical bug where B happens. Then tried C function but it also has a bug where D happens. Using external command E doesn't work because F..."

But hey -- neither I nor anyone else will try to reprogram something simpler. Or we can check if the library mentioned still has the bug in question.

Re: On Comments in Code

#66

Post by kelnos »

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 say as if it's an absolute, 100%-of-the-time statement! Obviously there are exceptions. That doesn't make the common-case rule useless or uninteresting. People should assume "most of the time" is the default implication about these sorts of "rules" unless otherwise noted.

Re: On Comments in Code

#67

Post by [deleted] »

kelnos wrote: post #64
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…

The worst, though, is when a comment tells you the valid input range, but it's wrong, because someone later changed the code and didn't update the comment. While this doesn't happen frequently, I've gotten bit by it enough that I will generally at least take a cursory look over the function body to verify that the comment is still correct. I wouldn't say this makes the comment useless, but it does reduce the usefulne…

[deleted]

Re: On Comments in Code

#68

Post by ravenstine »

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 and not everyone has the same skill or vision, so they might as well write a comment about what something does and the intent behind it rather than leave others guessing.

Re: On Comments in Code

#69

Post by squiggleblaz »

moeris wrote: post #50
alerighi wrote: post #48

Earlier quoted context omitted.

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…

That's more of an argument for them being overused, not for them being useless.

It's an argument for a certain code style, characterised by descriptive names and specific types. This calls for a language capable of e.g. doing maths with user-defined types, which not all languages can do.

I think one of the major motivators for the original style of code are legacy pressures and a concern about code width.

If every other function that manipulates temperature set points takes "int sp", then you're going to get a lot of pressure for consistency. A lot of programmers regard consistency as a goal in and of itself, and it's very easy to demand it during a code review. However, the demand for consistency prevents us from finding a new consistent target without excessive amounts of work. It may be better to reach a new consistency within a narrower scope, as long as a consensus has been reached to extended that consistency outwards. In this system, consistency should be viewed as a compromisable target: something that makes you ask a careful question. And when asking a question, take into consideration the propensity of the code author to view a question as a demand. If you're a senior and the code author is a junior, presume that means: ask a genuine question vocally; write down minutes of your discussion.

The code width concern is a bit silly, but for some reason we assume that things get weird when lines exceed 80 characters. That's easy to do.

Re: On Comments in Code

#70

Post by ericbarrett »

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…

This is maybe OK until you get a library user who doesn’t know what “ctx” means and now you have another Discord ping or GitHub issue. Just write the documentation.
Post reply on HN