Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Useful and useless code comments

blog.jim-nielsen.com

Post reply on HN
Print view View original

41–50 of 181 posts

Re: Useful and useless code comments

#41

Post by tharkun__ »

shusaku wrote: post #32
tharkun__ wrote: post #29

Earlier quoted context omitted.

I imagine you will use this in more than one place in the code. Why does it need a comment? Naming the function should be enough for most of it. Other languages probably aren't better at specifying the "in meters" part either, are they?

The name of the function won’t necessarily reveal the algorithm used in the implementation

By all means, if the specific algorithm isn't important I would totally be onboard with you in naming it after what the purpose is instead!

Feels like the difference between inlining quicksort vs. calling quicksort() vs. calling sort(). In some situations you really are on a level where you need to know you are calling mergesort() and not quicksort() but some are fine with sort(). I doubt there are many examples of code I'd argue for inlining.

Re: Useful and useless code comments

#42

Post by almostdeadguy »

For the most part I take no issue w/ the style of comments that act as a statement of intent.

It only becomes a problem when comments are used to paper over the author's own indifference to making the code itself legible, and that's where I expect critiques like this truly come from. Comments without legible code do not help, as the comments are not a proof of correctness or verification that the author's intent has been carried out. You still need to read the code to understand the program.

Code legibility is not unlike legibility in written language. Short sentences and paragraphs, clear transitions, well-defined hierarchy, consistent structure. Say more with less. Comments are often like footnotes: they elaborate upon the author's intent, provide a mental palette cleanser, elaborate on a digression in a way that limits distraction, or occasionally break the fourth wall.

Comments are improper when they try to serve other means. For instance comments about invalid uses of a function/class/etc. when the type system can be used to prevent illegal usages of code. Or when comments are used to explain what is happening in extremely branchy, anti-modular, or otherwise illegible code.

Re: Useful and useless code comments

#43

Post by vSanjo »

tylorr wrote: post #31
whoisjuan wrote: post #27

Earlier quoted context omitted.

This is something you can quickly see with Git. If the comment lines are older than the code lines you can at least start with the assumption that the comment might be outdated. That’s more useful than dealing with stale documentation which can also be outdated. At least with code comments you have contextual proximity.

This sounds like a great idea for an editor plugin.

1. Iterate through all blocks of comments. 2. Determine if there have been updates within the block of comments first (one line of three updating, for example). 2. For each block of comments, find the proceeding block of code. 3. Compare the last update of comments to the last updates of the code. 4. Warn the user when it's over a threshold.

Something like that?

Re: Useful and useless code comments

#44

Post by LukeShu »

shusaku wrote: post #32
tharkun__ wrote: post #29

Earlier quoted context omitted.

I imagine you will use this in more than one place in the code. Why does it need a comment? Naming the function should be enough for most of it. Other languages probably aren't better at specifying the "in meters" part either, are they?

The name of the function won’t necessarily reveal the algorithm used in the implementation

Yeah. I'd name the function something like `earthDistance` or `sphereDistance`, and then still have the "what" comment saying "haversine distance formula" inside of the function.

Re: Useful and useless code comments

#45

Post by Someone1234 »

When I was doing CS in college, bad commenting was an academic requirement: As in your grade would be worse if you commented appropriately.

Over multiple courses including software engineering, comment quality and or correct use of comments was never in the syllabus.

But in several courses they wanted to see the code heavily commented, to the point where you were just re-writing the code as a comment and getting a green tick instead of a red "more comments!" note. I legitimately believe that my educators just didn't know any better themselves.

These days I live by the mantra: Comment to explain WHY not HOW, since the WHY is lost to time whereas the HOW is often self-descriptive.

PS - [0]Still my favorite comment of all time. I'm still pissed that someone tried to remove it from the article on Wikipedia (in particular as the comment is almost as famous as the code).

[0] https://en.wikipedia.org/wiki/Fast_inverse_square_root#Overv...

Re: Useful and useless code comments

#46

Post by tonteldoos »

A number of people have touched on the fact that comments (even 'obvious' ones) provide boundaries, context and intent. I very much agree with this, with a couple of additional comments somewhat particular to embedded development:

- Compared to most user facing development, where probably >75% of code is purely for interaction (and potentially more repetitive, obvious, and readable), a LOT of embedded code is not so readable, and quite often context is key. Good comments (even on apparently obvious code) almost always carry some context (why do this here, and why in this order, why the specific delay before reading the ADC, etc)

- Because almost all the code is in some way business logic, it is definitely easier at times to read the flow of comments, rather than work out directly from the code which register someone is trying to set, and why, or why some seemingly arbitrary value is being incremented (that is actually being read by a parallel task somewhere else)

- As always, good comments are as much for yourself six months from now, as for the guy replacing you 6 years from now. Sometimes, it is just a good way to document your thought process, as well as provide reasonably up to date system documentation, since ACTUAL design documentation almost always gets neglected.

Basically - comment as much as you can, and as much as you need. Try and keep it up to date. It doesn't matter if it's seemingly obvious, or discussing the reasoning behind a particular architectural decision. Nobody I know has ever complained about too many comments, and if anything, more would have always been better.

Re: Useful and useless code comments

#47

Post by emodendroket »

mumblemumble wrote: post #15
hcarvalhoalves wrote: post #6

IMO, if I feel the need to add comments to explain code blocks like this: > // Add a horizontal scroll bar > hScrollBar = new JScrollBar(scrollBar, HORIZONTAL); > add(hScrollBar, BorderLayout.SOUTH); It's a sign I should be writing code that reads more like: > addHorizontalScrollBar()

Meh. If you're only doing it once, then I'd argue that the main practical difference between // Add a horizontal scroll bar hScrollBar = new JScrollBar(scrollBar, HORIZONTAL); add(hScrollBar, BorderLayout.SOUTH); and (assuming scrollBar is not a local variable) void addHorizontalScrollBar() { hScrollBar = new JScrollBar(scrollBar, HORIZONTAL); add(hScrollBar, BorderLayout.SOUTH); } ... addHorizontalScrollBar(); is wh…

I'd say it's the enforcement. It's like how YARD docs convey the same information as built-in compile-time type declarations, except you can't trust them. So you start ignoring them, forget to update them yourself, and kick off a vicious cycle.

Re: Useful and useless code comments

#48

Post by wyqydsyq »

> I find them useful as I write code because they allow me to state my intention (in plain English), translate it to code, then compare statements and see how well I’ve achieved my goal.

IMO this is exactly what unit tests should be used for. Replace these comments with unit tests and you're doing TDD. The practical difference is by stating your intention as unit tests, you not only verify your initial implementation is correct but also that any future changes remain correct.

Re: Useful and useless code comments

#49

Post by ninthcat »

bdcravens wrote: post #16

I generally save comments for WTF code, or to put links that document what's going on. I try to abstract things as a lot of folks are mentioning here, but that just pushes things to another place. Eventually someone is going to need to debug that code. Here's a Puppeteer example, where text is being split into nodes to extract based on line breaks: /* https://medium.com/@roxeteer/javascript-one-liner-to-get-elements-…

If you rewrite it so it's no longer a cryptic one-liner, it's probably easier to understand this way without a comment than the other way with one.

    return this.page.$eval(selector, (node) => Array
      .from(node.childNodes)
      .filter((child) => child.nodeType == Node.TEXT_NODE)
      .map((child) => child.nodeValue)
      .join('')
      .replace(/\s+/g, ' ')
      .trim()
    );

Re: Useful and useless code comments

#50

Post by mattacular »

emodendroket wrote: post #47
mumblemumble wrote: post #15

Earlier quoted context omitted.

Meh. If you're only doing it once, then I'd argue that the main practical difference between // Add a horizontal scroll bar hScrollBar = new JScrollBar(scrollBar, HORIZONTAL); add(hScrollBar, BorderLayout.SOUTH); and (assuming scrollBar is not a local variable) void addHorizontalScrollBar() { hScrollBar = new JScrollBar(scrollBar, HORIZONTAL); add(hScrollBar, BorderLayout.SOUTH); } ... addHorizontalScrollBar(); is wh…

I'd say it's the enforcement. It's like how YARD docs convey the same information as built-in compile-time type declarations, except you can't trust them. So you start ignoring them, forget to update them yourself, and kick off a vicious cycle.

This is an often used example in defense of not writing comments but in practice I rarely have encountered an out of date or misleading inline comment. In my experience, everything in code tends to stay up-to-date because it is often written and reviewed by multiple people who have some incentive to keep it correct. It's other documentation outside of code that frequently goes stale.
Post reply on HN