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

21–30 of 238 posts

Re: On Comments in Code

#21

Post by chowells »

Sometimes you come back to a block of code you wrote a long time ago and go "what?" enough times that you go ridiculously overboard documenting it just to create the illusion of understanding it quickly the next time.

I still don't understand https://gist.github.com/chowells79/996f2749b088d287937e3eff1... on the first read, even with the ridiculous overdocumenting. On the plus side, it's clear enough what it does, even though the details of "how" are hard to follow.

Still, if there ever was a case for documenting the "how" over the "why", that code is it. It's pretty easy to understand why that code exists. It's actually quite hard to follow the details of how it does it. Those comments are excessive, but they do cut the time it takes to rediscover the "how" whenever I get curious.

Re: On Comments in Code

#24

Post by isbvhodnvemrwvn »

nicoburns wrote: post #16
Nicksil wrote: post #5

Earlier quoted context omitted.

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

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

Re: On Comments in Code

#25

Post by timdaub »

I try to never write a comment about anything that I've already written in code. I only add information that is necessary to know to run the code but is not in the code.

I do it like this as I think that conceptually duplicating code logic through e.g. comments can be dangerously imprecise. E.g. when someone changes the code (and not the doublicating comment), there are no checks in place for this mismatch of code and comment to be caught by e.g. a test.

Re: On Comments in Code

#26

Post by jbay808 »

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;

What would be your opinion of this comment, though?

  // Reset the counter for the next run
  total_count = 0;

Re: On Comments in Code

#27

Post by ferdowsi »

Most documentation in dynamic languages I've encountered (like JS) have been wordy attempts at documenting function arguments. This almost always falls short of the goal. Describing object shapes and types is difficult in documentation, especially in languages that mutate objects willy-nilly. TypeScript and mypy are really essential documentation tools for that reason; they liberate developers from the Sisyphean task of describing object shapes and mutations and lets them write documentation that is actually useful.

Re: On Comments in Code

#28

Post by ozim »

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…

Javadoc comments problem begins as soon what is in javadoc stops being true.

So you are usually better of reading the code anyway because you cannot trust that some dev updating code updated javadoc as well.

When something goes wrong I usually have to do is to dig into GIT history and see when and what changes were connected.

Re: On Comments in Code

#29

Post by bregma »

aequitas wrote: post #2

Code is for computers to make them do exactly what you want them to do, comments are for your co-workers (and you) to make them understand what you actually meant to achieve.

All code is literature intended exclusively for humans. Computers read machine instructions; they're incapable of reading code. Know your audience.

Re: On Comments in Code

#30

Post by latchkey »

jbay808 wrote: post #26
Nicksil wrote: post #5

Earlier quoted context omitted.

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

What would be your opinion of this comment, though? // Reset the counter for the next run total_count = 0;

why are you resetting the counter?
Post reply on HN