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

211–220 of 238 posts

Re: On Comments in Code

#211

Post by joppy »

RandallBrown wrote: post #61
simonw wrote: post #57

I care much more about revision history than I do about comments. When I'm trying to figure out code I do it in "git blame" mode - what I'm hoping for is a single, atomic commit that links back to an issue thread. Ideally that issue thread will have all of context I need to fully understand the change. This works great in codebases that are designed to be read in that way, which is why I'm so keen on every commit com…

Definitely. Commit messages are updated with the code automatically. Comments seem to become out of date almost immediately.

Isn’t this an argument for better code review, rather than against comments?

Re: On Comments in Code

#212

Post by rwallace »

dstick wrote: post #170
benrbray wrote: post #165

Earlier quoted context omitted.

Tests are useful, but the big reason that comments are useful is that they are co-located with the relevant code. At the moment, I don't know of any tools that allow you to 1) specify which lines of code are directly relevant to a particular test case, even when the surrounding code changes and 2) see a list of test cases related to the currently highlighted line. I'm sure it would be possible to build such a tool, b…

Exactly. And then the question remains: why? Why hate comments so much? I never got that

I would conjecture that it has two components:

1. Ancestral memory of programming in languages like assembly or early Fortran where your code was going to be spaghetti because the language was capable of little else, so it had to be drenched in comments that would be unnecessary in a better language.

2. Overreaction to personal memory of overzealous professors who demanded assignments be drenched in excessive comments.

Re: On Comments in Code

#213

Post by retsibsi »

pjerem wrote: post #178
retsibsi wrote: post #163

Earlier quoted context omitted.

People often insist on this point, and I still don't get it. Honestly it comes across as intentionally exaggerating a claim beyond reason, in order to make it sufficiently counterintuitive to sound clever. The point of the program is to get the computer to perform some task; the way we get the program into the computer is to write code. You can say we're writing code for the compiler if you want to be pedantic; or yo…

> But what do you actually mean by insisting that no, the code isn't for the computer at all, it's solely for other humans? By insisting on this, I mean that, at any given time, if I have the choice to write code that is easily readable by an human XOR a code that is easy to execute (fast), I will always choose the first. And it’s not a dogmatic ideology : sure there are tradeoffs where writing efficient code is need…

That seems reasonable enough when you unpack it; I just don't see the point of stating it in falsely absolute terms. Maybe (almost certainly) I'm too much of a literalist, but instead of saying 'always' and then clarifying in the next line that of course you don't mean always -- or saying that code is for humans not computers, when you mean that code is for humans and computers -- why not say what you mean the first time around. Maybe it'll be a bit less pithy, but it will also drag you into fewer discussions with people like me :)

Re: On Comments in Code

#214

Post by majewsky »

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.

This is Damian Conway's "coding in paragraphs" advice, and in my experience, it's the single best advice for more readable code. When you have a large function, split the code into blocks with a heading comment on each section. That way, you can skim through the function body quickly by just reading the headings, then dive deeper into whatever block you're interested in. Like section headings on an article.

Re: On Comments in Code

#215

Post by OJFord »

benrbray wrote: post #165
pmoleri wrote: post #125

Earlier quoted context omitted.

Or you can write tests for every single not there case. Just bringing it up, I usually write lots more comments than tests. I also encourage my teammates to add comments. The problem is when one can't really explain why the simpler approach didn't work. That requires more research just to write the comment, but I think it pays off really quick.

Tests are useful, but the big reason that comments are useful is that they are co-located with the relevant code. At the moment, I don't know of any tools that allow you to 1) specify which lines of code are directly relevant to a particular test case, even when the surrounding code changes and 2) see a list of test cases related to the currently highlighted line. I'm sure it would be possible to build such a tool, b…

> Tests are useful, but the big reason that comments are useful is that they are co-located with the relevant code.

That's a not-often-talked-about (that I see anyway?) thing I really like about rust - I don't get to use it much, but when I do I think having 'doc tests' alongside comments heading a function and 'module tests' at the bottom of the same file is great.

Re: On Comments in Code

#216

Post by lucideer »

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…

This is great if you're using a loosely typed language (like JS), but I think the need for this is why things like Typescript are gaining in popularity.

I used to love the eslint-enforced jsdoc in a repo I maintain, but since we embarked on a TS migration, it has become painfully redundant in 90%+ of cases (there are cases where the jsdoc contains extra commentary/context that TS doesn't cover, but I think those cases are covered by the author's other comment types).

So given the above, I think it's notable that you are referring to JSDoc (and by extension JS) whereas the author is referring to Javadoc (and by extension Java). The language choice is particularly important here.

Re: On Comments in Code

#217

Post by lucideer »

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…

JSDoc !== Javadoc

The reason I say that is because the language features (or lack thereof) are a big contributor to the need for JSDoc/Javadoc.

i.e. JSDoc adds much more to Javascript than Javadoc adds to Java.

For example, there is much less need for JSDoc in a Typescript project.

Re: On Comments in Code

#220

Post by Cthulhu_ »

slver wrote: post #203
BearfootCoder wrote: post #191

Earlier quoted context omitted.

The inverse of this is also useful: // Dear maintainer, // The code which follows was hacked together under desperate pressure. // It's not smart. // It's not doing anything really subtle. // It's the only thing we could get to work in the time. // If you want to chuck it and replace it, you absolutely should.

It's useful, until you realize you have this on 90% of your code.

That's when a full rebuild can be justified.

I'm doing that atm, but I think my predecessor lacked the humility to admit that his code was bad, which is how it went up to 150K of code that basically concatenates XML, converts it to JSON and concatenates HTML on the front-end from the result.

Post reply on HN