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

71–80 of 238 posts

Re: On Comments in Code

#71

Post by ridiculous_fish »

da39a3ee wrote: post #59

I find Rust crate code to be quite difficult to read sometimes because it contains a lot of comments and executable examples destined to be incorporated into auto-published (and auto-executed) documentation. That's a fine thing of course, but it would be nice if there were facilities to see "just the code and code comments". A somewhat random example is https://github.com/ogham/rust-ansi-term/blob/master/src/styl...

I wish for a text editor that shows the comments to the side of the code, like in a split pane.

Re: On Comments in Code

#72

Post by qayxc »

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…

> But we can change around the name of the parameters like this and use proper strict types

Sometimes. Other times proper strict types aren't possible because the language doesn't support them (many scripting languages, C, etc.)

Assuming this is C, even a type like "celsius_degree_t" tells me nothing about the valid range. Am I supposed to just try it out and see what error code I get or are we back to looking at the implementation? In the case of C this will most likely involve locating and opening a completely different file whose name doesn't even have to be related to the header file.

The comment also doesn't need to be about all parameters and can contain additional information that's non-trivial to determine: is the function thread-safe, are there performance implications, is there notable resource usage, and so on.

Python in particular is notorious for having optional (keyword-) arguments and polymorphic arguments. Proper naming schemes are impossible in this case (lest you accept monstrosities like "node_as_id_or_name_or_object" as proper argument names) and type annotations have only very recently (as of 3.10) become somewhat sane. Type annotations don't help with kwargs, though.

TL;DR it greatly depends on the programming language and its capabilities whether naming and types alone can replace comments.

Re: On Comments in Code

#73

Post by macintux »

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

Re: On Comments in Code

#74

Post by simonw »

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.

Re: On Comments in Code

#75

Post by nicoburns »

isbvhodnvemrwvn wrote: post #24
nicoburns wrote: post #16

Earlier quoted context omitted.

I find it's often useful to put a 'what commment' on a block of a few (2-10) lines of code. Then you can skim through the function without reading every individual line of code.

You might as well be able to extract a method with a meaningful name then.

That then makes the code non-linear, which IMO makes it a lot less readable in most circumstances.

Re: On Comments in Code

#76

Post by nicoburns »

firebaze wrote: post #42
nicoburns wrote: post #16

Earlier quoted context omitted.

I find it's often useful to put a 'what commment' on a block of a few (2-10) lines of code. Then you can skim through the function without reading every individual line of code.

To me it's actually faster and easier to read code instead. This is because i generally don't trust "what" comments - either I know the code already or I don't, and if I don't, then I don't trust the "what" comment fully, so I both have to parse "what" and code. A "why" comment usually ages well, so I generally trust it and can use it to better parse the code and its intentions. So I belong in the "what only for API…

Do you also read through every function call (at least the first time you encounter a given function)?

Re: On Comments in Code

#77

Post by adonnjohn »

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.

Should my 'why' comment go further than a Jira number?

Re: On Comments in Code

#78

Post by GuB-42 »

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…

Libraries are an exception. Here, from the article, talking about Javadoc.

> These comments may be useful for API:s exposed externally, but in an application where you have access to all the source code, they are mostly useless.

Re: On Comments in Code

#79

Post by Normal_gaussian »

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 find an issue link only works if e is a good enough comment alongside it (ie. Attempting to eliminate this mutex is bug prone, see for archiyectures and their problems).

Re: On Comments in Code

#80

Post by isbvhodnvemrwvn »

nicoburns wrote: post #75
isbvhodnvemrwvn wrote: post #24

Earlier quoted context omitted.

You might as well be able to extract a method with a meaningful name then.

That then makes the code non-linear, which IMO makes it a lot less readable in most circumstances.

It depends, if it needed a comment in the first place it likely was at a different (likely lower) level of abstraction than the rest of the code in that method.
Post reply on HN