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

81–90 of 238 posts

Re: On Comments in Code

#81

Post by Normal_gaussian »

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…

The funny thing is, when someone writes really 'clever' code, I need a why more than ever. Why isn't this simpler?

Re: On Comments in Code

#82

Post by philosopher1234 »

GuB-42 wrote: post #78
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.

All code is library code

Re: On Comments in Code

#83

Post by TrianguloY »

There are 4 main types of comments I use:

- javadocs: at the top of the function. Explains what you need to expect from it, very useful when autocompleting (yes, you can go read the code...but that's slow)

- block description: before a bunch of lines. Explains what they do without need to read and understand them all, so you can read them faster.

- line description: at the right of a line of code. Explains the use of a specific variable, the reason you used a function call, etc.

- flow descriptor: the line after an if, an else and other path divisions like while or for. Explains why the code took that path. Useful when you need to understand the context of a specific line.

Re: On Comments in Code

#84

Post by gbear605 »

pc86 wrote: post #13
ithronmellon wrote: post #6

Earlier quoted context omitted.

What belongs in comments describing API methods, why belongs everywhere else.

If it's impossible to make "what" clear through the code itself.

If a method is part of an API that might be used by developers external to your team, they don’t want to be looking through your code to figure out how to use your methods.

Re: On Comments in Code

#85

Post by pjerem »

ozim wrote: post #31
watwut wrote: post #19

Earlier quoted context omitted.

To me the above quote says that author never worked with anything more complicated or more big then simple crud web app.

To me it says that author is perfectly aware that people are not updating Javadoc comments or normal comments as well.

If your method documentation is out of date, the problem is not about the doc.

The problem is that someone on your team drastically changes existing methods behavior instead of writing new ones, and by doing that, is changing the behavior every historical caller expected.

I really think that if your changes are so important that they need the doc to be updated, it’s probably that you should write a brand new method. Changes in an already called method should only concern implementation details.

Re: On Comments in Code

#86

Post by philosopher1234 »

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…

Why are method names priveleged over comments? They're both text read for human understanding. Why must the full documentation/definition for a function fit into the length of a method? These are silly restrictions, and lead to worse code.

Re: On Comments in Code

#87

Post by Normal_gaussian »

adonnjohn wrote: post #77
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?

Absolutely. I worked a codebase that was littered with ticket numbers for a few years; many members of the team religiously added them but never read them. How do we know? Self hosted issue system and access logs. New starts would read a couple and that was it.

A ticket is a really opaque way of showing something. If you click the issue you're now going through several tangentially related comments and a few MR back and forths just to work out if its even useful to you. People will stop bothering to even open the link unless they are really stuck.

Whack a summary comment and then by all means include the link, but the comment is what most people will use.

Re: On Comments in Code

#88

Post by nytgop77 »

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…

Full agreement.

Unfortunatly it is a story, that is set to repeat 3 times.

There is a similar tragedy of outdated documentation.

And then the final part of the trilogy is named "outdated and even misleading naming" (vars/functions).

In all cases, one should have same amount of trust as with weather forcast or politician's speech. Trusting 100% would be naive, but complete dismisall would be foolish as well.

Re: On Comments in Code

#89

Post by _old_dude_ »

rrose wrote: post #62
wongarsu wrote: post #51

Earlier quoted context omitted.

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

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

Re: On Comments in Code

#90

Post by jeddy3 »

d23 wrote: post #58

The only thing I would add is that header-style comments are immensely helpful for "chunking" the code into distinct sections. I first saw this recommended in Code Complete, and it stuck with me, since I've seen it in a number of other domains. It's a basic part of cognitive psychology that makes information processing and retention much easier.

Can you explain further what you mean by header-style comments?

I'm having trouble drawing up a distinct example.

Post reply on HN