Live data from Hacker News

Useful and useless code comments

blog.jim-nielsen.com

141–150 of 181 posts

Re: Useful and useless code comments

#141
I probably end up with numerous "useless" comments in my code.

That's because I write my code's doc string first (or JavaDoc or whatever), then write the body in English comments or pseudocode on rare occasion, then write the code beneath and between the conments that are my English plan.

I will also write additional comments about anything unintuitive, complex or unusual, even slightly, because I know that the code will be read many more times in the upcoming decades. (I have code I wrote in 1994 in production at one company, and another hitting its 20th anniversary this year still in production. Do you even remember libg++? Me neither, but the code still uses it...)

Re: Useful and useless code comments

#142

Earlier quoted context omitted.

If that line of code is not obvious, why not add a function and do add_vertical_scrollbar()

I can't think of a single benefit of a function over a comment for a piece of code that's only used once. The downsides of the function: - Unless the function is extremely clear like max() or min(), you will have to read the function and jump around the code. I feel people underestimate the cognitive overhead required for this. This gets worse the more arguments are required to pass around. Linear code is much easier…

>I can't think of a single benefit of a function over a comment for a piece of code that's only used once.

The call stack becomes very organized and readable when debugging.

Re: Useful and useless code comments

#143

I’m on the same page. Just look at the given example. Does it look wasteful to say that you’re adding a vertical bar when you have the following line of code?: // Add a vertical scroll bar vScrollBar = new JScrollBar(JScrollBar.VERTICAL); add(vScrollBar, BorderLayout.EAST); Perhaps. But the comment is making a lot more than simply describing what’s below of it. The comment is doing the following things: - It’s creati…

> But you cannot expect everyone to have the same proficiency you do. Writing good code, also means writing code that a newbie can at least comprehend. If you're writing example code or documentation, by all means, add this kind of comment. Otherwise, if someone can't comprehend these particular two lines without reading the comment, they need to get back to the drawing board. You can't have noisy code like that in p…

Books need no covers, because if a reader cannot comprehend a book title from the book content, then (s)he must go back to the school. /s

Re: Useful and useless code comments

#144

The article makes some fair points. And once you move beyond the explaining-to-yourself stage, there's yet another reason to have such “useless” comments: quick code navigation. Finding the place in the code where X is being done would be perfectly feasible by consciously reading the code, but I want to save that energy. Letting my visual cortex pattern-match on a syntax-highlighted comment that looks a certain way i…

As always, there's a flipside.. I find code with lots of comments and "fluff" to be a drag to read and navigate and generally work with. I would rather have less to scroll to begin with, than have comments help me jump to a specific spot. For example, I just replaced a well documented pair of functions that compute a checksum. The original implementation was about thirty lines, including comments and empty lines. My…

Why not just use an obfuscator? It produces clean and compact code. You can disable mangling of names and reformat code after obfuscation using a formatter with your own set of rules. IMHO, it better to use tool designed just for that, instead of performing obfuscation by hands.

Re: Useful and useless code comments

#145

I’m on the same page. Just look at the given example. Does it look wasteful to say that you’re adding a vertical bar when you have the following line of code?: // Add a vertical scroll bar vScrollBar = new JScrollBar(JScrollBar.VERTICAL); add(vScrollBar, BorderLayout.EAST); Perhaps. But the comment is making a lot more than simply describing what’s below of it. The comment is doing the following things: - It’s creati…

If that line of code is not obvious, why not add a function and do add_vertical_scrollbar()

In fact, coding in paragraphs and factoring chunks of code into separate functions are not mutually exclusive or contradictory; coding in paragraphs facilitates such factoring.

It's very easy to generate code that "jumbles" tasks. You set "x" coordinate of your point in one place, then do some calculations for "y" coordinate, then set it, then do something unrelated, and then set the color of your point. Such code does not make it obvious that you could create a "set_point(y, y, color)" function.

When coding in paragraphs, you organize your code into chunks so that each one "does one thing and does it well". It's natural then to consider whether a particular chunk could be a separate function.

Often it is, but sometimes it is not. First, creating a separate function has costs: choosing an appropriate name, designing an interface, etc. If the name and/or interface are not well-designed, a separate function can decrease readability: consider a function called "fix" that has 10 positional arguments...

Second, especially if your chunk is within a loop or two, the code may be too tightly coupled with the state within your code. You would need additional and perhaps modifiable "state" parameters to your function, making the resulting code more complicated and less comprehensible than the original one.

And of course, if your hypothetical function cannot be inlined (perhaps because your language does not even have the facility, or for other reasons), you would pay the price of a function call, which may matter in a tight loop.

In general it's always good to consider factoring chunks of code as a separate function, but sometimes upon this consideration you should reject it.

Re: Useful and useless code comments

#146

Earlier quoted context omitted.

I can't think of a single benefit of a function over a comment for a piece of code that's only used once. The downsides of the function: - Unless the function is extremely clear like max() or min(), you will have to read the function and jump around the code. I feel people underestimate the cognitive overhead required for this. This gets worse the more arguments are required to pass around. Linear code is much easier…

>I can't think of a single benefit of a function over a comment for a piece of code that's only used once. The call stack becomes very organized and readable when debugging.

The call stack becomes deeper. I'm not sure that's always a good thing.

Re: Useful and useless code comments

#147
One of my guilty pleasures is writing code comments, even in places where it might be “obvious” about what that block or line is doing. To me, it’s less mentally taxing to read a plain language description of the logic than to decipher that by reading the code. Of course the caveat is that if someone modifies that part of the code and doesn’t update the description, then it could be confusing. I much prefer this to the culture that seems to prevail among some languages (such as Ruby) that the code should be self-documenting.

It is also my experience that writing comments (even the so-called flower boxes, e.g., Javadoc/JSDoc) force me to think about what the code is doing and its readability to future maintainers. If I find myself having to over-explain the block, I might rewrite it or extract it out to a function or class, the name of which summarizes the intent, therefore eliminating the need for the comment.

Re: Useful and useless code comments

#148

Earlier quoted context omitted.

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.

Consider yourself lucky then. I've wasted tons of time because of them.

Re: Useful and useless code comments

#149

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…

One additional of benefit of commenting: if you cannot write comment for a block of code, then you either a) doesn't understand code well, b) code is useless and must be deleted.

Most of the developers, which hate comments, hate them because they cannot write proper comments, i.e. they are hiding their own weakness, to look smarter than they are.

Re: Useful and useless code comments

#150

Earlier quoted context omitted.

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.

Consider yourself lucky then. I've wasted tons of time because of them.

Consider reviewing of your code review process.
Post reply on HN