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

11–20 of 238 posts

Re: On Comments in Code

#11

Post by rav »

Sometimes, as you become a better programmer, a comment that you thought were a "why" comment is now clearly a "what" comment. One programmer's "magic super-efficient pointer gymnastics" in C is another programmer's standard idiom. When working on a large project as a team, most of the project may be run-of-the-mill code for most of the team, and so it doesn't warrant "what" comments. However, there will be times when you have to introduce coding idioms that are foreign to everyone on the team, in which case a "what" comment may be warranted.

For example, a standard 5 year old React codebase probably used to contain a lot of class-based components and now is probably switching to function-based components with hooks. I know the first time I did a code review on my colleague's code that introduced some weird hook concept - I asked for some more comments to explain what magic was going on. I would probably not ask for such a comment today now that everyone is more or less familiar with hooks and function-based components.

Re: On Comments in Code

#12

Post by javert »

I have a personal rule: If I need a comment, it goes at the beginning of the function.

This neatly groups the comment with the code it applies to.

Occasionally I have to make a function "just" for this grouping purpose, but that's fine.

Re: On Comments in Code

#13

Post by pc86 »

ithronmellon wrote: post #6
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.

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

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

Re: On Comments in Code

#14

Post by mpoteat »

javert wrote: post #12

I have a personal rule: If I need a comment, it goes at the beginning of the function. This neatly groups the comment with the code it applies to. Occasionally I have to make a function "just" for this grouping purpose, but that's fine.

This is also my practice. Any code that is complicated enough to require a special comment is also complicated enough to be its own function.

Re: On Comments in Code

#15

Post by jka »

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.

Nicely said. One small adjustment I'd suggest -- because I care a lot about setting incentives -- is that we generally want not just _more_ "why" comments, but in particular concise "why" comments that empathize with and improve the life of future developers. They're a kind of message-in-a-bottle conversation.

Re: On Comments in Code

#16

Post by nicoburns »

Nicksil wrote: post #5
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.

>Codes needs "why" comments, not "what" comments. Indeed. While there are exceptions, "what" comments will usually only add noise thus making things more difficult. This isn't necessary: // Total count int total_count = 0;

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.

Re: On Comments in Code

#17

Post by probably_wrong »

I'd like to argue against the author's disdain for javadoc-like comments.

> 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 feel that this is a very inefficient approach to coding. If you tell me what the function does, what its valid inputs are, and what it returns then I don't need to look at the code at all.

More so when I'm collaborating with people outside my area of expertise: a colleague of mine wrote a function to "convert molecule SMILES into their neutralized form". What does it do? Beats me, I'm not a chemist. But thanks to the comments I don't need to know, and I'm grateful for that.

Re: On Comments in Code

#18

Post by aliasEli »

The author is not very positive about JavaDoc. I agree that using it everywhere is probably overkill, but when you are writing a library JavaDoc can be useful for documenting it.

Re: On Comments in Code

#19

Post by watwut »

probably_wrong wrote: post #17

I'd like to argue against the author's disdain for javadoc-like comments. > 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 feel that this is a very inefficient approach to coding. If you tell me what the function does, what its valid inputs are, and what it returns then I don't need to look at the code at all. More…

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