On Comments in Code • Hacker News Board

Re: On Comments in Code

#31

Post by ozim » Tue, Jun 15, 2021, 7:28 PM UTC

watwut wrote: post #19

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.

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

Re: On Comments in Code

#32

Post by rrose » Tue, Jun 15, 2021, 7:28 PM UTC

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;

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

Re: On Comments in Code

#33

Post by jbay808 » Tue, Jun 15, 2021, 7:29 PM UTC

timdaub wrote: post #25

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 an…

If you have really good test coverage that might be okay, but otherwise, how do you know if the code is doing what it's intended to do?

If I see a line that looks like it might be a bug, or an unnecessary duplication, how do I know if it's a mistake or not?

Re: On Comments in Code

#34

Post by bregma » Tue, Jun 15, 2021, 7:30 PM UTC

I have never cursed an author for having too many comments. There are many cursed developers out there after my long career.

Re: On Comments in Code

#35

Post by jbay808 » Tue, Jun 15, 2021, 7:31 PM UTC

bregma wrote: post #29

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.

Humans wouldn't care so much about semicolons, but I do want the compiler to understand my code, too.

Re: On Comments in Code

#36

Post by teknopaul » Tue, Jun 15, 2021, 7:33 PM UTC

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…

nothing wrong with the tool, the issue is with the comments that exist and those that don't.

getFoo() does not need a comment.

if it does, (it shouldn't) and its JavaScript, JSDoc is a fine format.

if getFoo() does need a comment, consider changing the code so it doesn't.

Code is read much more often than its written: so be concise.

If the docs can be automated by a simple tool, by definition, they were not necessary.

Re: On Comments in Code

#37

Post by dcolkitt » Tue, Jun 15, 2021, 7:33 PM UTC

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.

I mostly agree with you, but there are certain cases where you’re making weird and non-intuitive performance optimizations and have to explain “the what”.

Re: On Comments in Code

#38

Post by krylon » Tue, Jun 15, 2021, 7:41 PM UTC

jaywalk wrote: post #9

krylon wrote: post #7

Earlier quoted context omitted.

A comment like "This method opens a separate database connection so as not to mess with the ongoing transaction" or some such would be rather helpful, though.

Within the code I write, I can't think of a scenario where that wouldn't be obvious. But if it is indeed not obvious, then I agree that would be a helpful comment.

I guess that was what I was trying to say. Make your code as obvious as possible, and use comments to explain what's not obvious.

Although people have vastly different ideas of what is or isn't obvious.

Re: On Comments in Code

#39

Post by teknopaul » Tue, Jun 15, 2021, 7:42 PM UTC

ozim wrote: post #28

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.

Having said that you can spot bad code by its JavaDocs.

The most reliable Javadoc is @author, git tells you the author, @author tells you who the code was copy/pasted from.

Re: On Comments in Code

#40

Post by nomel » Tue, Jun 15, 2021, 7:46 PM UTC

teknopaul wrote: post #36

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…

nothing wrong with the tool, the issue is with the comments that exist and those that don't. getFoo() does not need a comment. if it does, (it shouldn't) and its JavaScript, JSDoc is a fine format. if getFoo() does need a comment, consider changing the code so it doesn't. Code is read much more often than its written: so be concise. If the docs can be automated by a simple tool, by definition, they were not necessary…

I generally enjoy a brief description of the overlying concept, at the top of each function. I don't care to know how a function is implemented as much as rough details to help me navigate the new/forgotten code space/context. Usually, a quick example of usage, within some relevant context, is enough to push me in the right direction.

If I have to read every line of implementation to know wtf is going on, then I'm probably going to have a bad time.