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

131–140 of 238 posts

Re: On Comments in Code

#131

Post by cmckn »

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?

Yes. Unless your explanation is thousands of words (which it probably shouldn't be), just inline it. I only speak for me, but if I had to look up (potentially multiple) Jira tickets just to understand what was happening in a source file, I wouldn't be at that job very long.

Re: On Comments in Code

#132

Post by ElijahLynn »

dcolkitt wrote: post #37
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”.

Definitely agree there are still cases where "what" is useful. Especially in some code that I come across that I just can't grok (e.g. badly named things), I start writing what it does just as a rubber duck method, and I don't have capacity to refactor the whole thing right then, at least I will leave behind a "what" comment because if I had trouble grokking what it does then someone else likely will too.

Re: On Comments in Code

#133

Post by xbp »

nytgop77 wrote: post #108
ozim wrote: post #28

Earlier quoted context omitted.

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.

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

Great point.. except for when you're dealing with a lead and/or reviewer that refuses to approve comments because "we write self-documenting code" yikes

Re: On Comments in Code

#134

Post by philosopher1234 »

xwolfi wrote: post #130
philosopher1234 wrote: post #86

Earlier quoted context omitted.

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.

Because writing a(a,b) is not ok even if comments are great, so why not make the method name a clear enough verb that comments are often unnecessary. The problem is that not everyone code under the same circumstance, even inside the same codebase: you have the new joiner that has to reverse engineer most of what he uses, the senior who did or touched enough that he doesnt even see the color code for comments, the rus…

Accepting that comments are sacrificial does not mean sacrificing them eagerly. In general, code with comments is better than code without.

Re: On Comments in Code

#135

Post by discobean »

Not always, but I noticed I often find I write my comments first on what I want to achieve like a sort of psuedocode in a very high level.

Then under each one-line comment I'd write the code that does what's written.

Re: On Comments in Code

#136

Post by azemetre »

teknopaul wrote: post #39
ozim wrote: post #28

Earlier quoted context omitted.

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.

Is this different from git blame or does @author take the info from git blame for you?

Re: On Comments in Code

#137

Post by tharkun__ »

neolog wrote: post #116
simonw wrote: post #74

Earlier quoted context omitted.

I love having commentary like that around, but I prefer to keep it in either the commit message or (more frequently) in the issue thread linked to from the commit. That way I can use as much space as I like for it and the timestamps make it clear that it's historical commentary, not a description of how the code works right now.

Some people advocate putting lots of stuff into commit messages, which makes me think I'm missing something -- commit messages are much less visible/accessible than comments in my workflow, so I don't expect my commit message to be seen. Do you always read the whole git history of a file before editing it? What interface do you use for that?

I prefer comments but yes. If something doesn't make sense, one of my first things to try is to check the `git blame` and see if there's anything recent (or close to when the bug reportedly appeared, such as between two versions). Sometimes the commit message tells me something but usually not, but just looking up the ticket number from the commit message on our issue tracker can be enough hint sometimes. Especially on our SaaS product, if a problem just popped up in Prod and especially if the bug seems both easy to reproduce and feels like "wasn't us" I'll make a quick guess on a 'known good version', try to reproduce and the `git bisect` to find the culprit. Not to blame but just to figure out what's wrong in a very easy way. Sometimes I can fix it easily from that or ping the person who made the boo boo and they will usually know how to fix it quickly.

In the context of regular development? I almost never do any of that.

Re: On Comments in Code

#138

Post by pmoleri »

ravenstine wrote: post #68
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…

When I started out programming I was taught that the code should "document itself" and that comments were an anti-pattern to writing good code. It took me a few years realize how idiotic that was and deprogram myself. It's one of those things that sounds nice, but once you've moved beyond a certain level of complexity you realize how impractical it is. The fact is that "good code" is often in the eye of the beholder…

I've seen people refactoring the code just to avoid writing a single line comment, like it's a dirty thing to do. After the refactor the new code is probably more readable, but not as good as it would have been with the comment.

Re: On Comments in Code

#139

Post by tored »

neolog wrote: post #116
simonw wrote: post #74

Earlier quoted context omitted.

I love having commentary like that around, but I prefer to keep it in either the commit message or (more frequently) in the issue thread linked to from the commit. That way I can use as much space as I like for it and the timestamps make it clear that it's historical commentary, not a description of how the code works right now.

Some people advocate putting lots of stuff into commit messages, which makes me think I'm missing something -- commit messages are much less visible/accessible than comments in my workflow, so I don't expect my commit message to be seen. Do you always read the whole git history of a file before editing it? What interface do you use for that?

If you use an IntelliJ based IDE you can view commit entries for each line in the gutter.
Post reply on HN