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

101–110 of 238 posts

Re: On Comments in Code

#101

Post by GuB-42 »

bregma wrote: post #34

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

I have.

And stripping comments before working on it is a thing I have done many times, on code I wasn't familiar with.

The biggest problem is lies. If you don't update your comments, don't write them. If you know someone less careful than you is going to take over and not update your comments, don't write them either.

And then, there are the redundant comments, the ones I see most often. For example

- Don't describe the function both in the header and source code, it is a useless copy-paste that will never be updated correctly. (mostly for C/C++)

- I know the syntax for declaring a constructor, thank you, you don't need to tell me that is is a constructor in the comments. And I can also guess that getX() gives me the value of X, no need to fill my screen with dozens of useless lines of comment.

- I don't need a comment to know who did what. We are under source control and we have a "blame" command.

- Don't use comments to disable code. Just delete it, it is not lost, we have history, and we are unlikely to need it anyways.

But the one that makes me rage the most is something like "int time; // the time". Not only it is useless, but you are not giving the info I want: the fucking unit! I've seen it way too often, sometimes with far from obvious units, like tens of microseconds. So if you want to put a comment, at least tell us the unit. Or better yet, don't comment anything and make your variable something like time_in_ms, or define a type.

Re: On Comments in Code

#102

Post by pjerem »

jaywalk wrote: post #4
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.

Code involves names of methods and variables which can greatly aid in understanding as well. I've always maintained that comments should only be in code to explain something that is not obvious. If you're calling the SaveUser function and passing in a new User object that you had just created, a comment of "Save the new User object" adds nothing but noise.

- Do you SaveUser to the database directly or do I have to somehow call something to validate the transaction ? - Once it’s saved, can I continue to use my User model or should I fetch the more complete one from the database ? - Does this even SaveUser to the database or on a temporary structure that will be fetched by our UserCreationBot ? - Does SaveUser checks if the username already exists or should I check myself before calling it ? - Does SaveUser checks that current user is allowed to create new users or should I check it before ? - What happens if SaveUser is called with a User with an empty password ? Does it means that the input is wrong or am I legitimately creating a user that can’t login?

Re: On Comments in Code

#103

Post by nicoburns »

isbvhodnvemrwvn wrote: post #80
nicoburns wrote: post #75

Earlier quoted context omitted.

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.

Yes, but that doesn't mean it doesn't benefit from being inline. I love being able to skim over the paragraph-comments to get the big picture and then dip into the details without having to jump to another file / part of the file and lose my context.

Re: On Comments in Code

#104

Post by pjerem »

teknopaul wrote: post #43
bregma wrote: post #29

Earlier quoted context omitted.

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

nonsense. code is intended for a computer by definition.

No. Code is intended for your teammates.

Compiled machine code is for your computer.

If you were addressing a machine, you would be writing 0s and 1s, because o boy do the machine know how to execute those little ons & offs.

Re: On Comments in Code

#105

Post by nonameiguess »

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. All that information dies when your organization migrates off of Jira years down the line and the issue ids no longer exist.

Re: On Comments in Code

#106

Post by [deleted] »

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…

[deleted]

Re: On Comments in Code

#107

Post by bostonsre »

Normal_gaussian wrote: post #87
adonnjohn wrote: post #77

Earlier quoted context omitted.

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…

I wonder if there are jira integrations that would bring ticket info into the ide. Although, I hate jira and would definitely prefer good git commits.

Re: On Comments in Code

#108

Post by nytgop77 »

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.

Same with naming in code.

Names do become misleading. Of course making callstack deep enough, will hide that.

Code reviews have same power to rectify both: naming and comment issues.

Re: On Comments in Code

#109

Post by bostonsre »

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.

I do something like this, but I write them as debug log statements so that you get the additional benefits from logging.

Re: On Comments in Code

#110

Post by slver »

I'm quite irritated by this train of thought "JavaDoc is useless because you can write a useless JavaDoc". Can't we get at least past elementary logical fallacies.
Post reply on HN