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

111–120 of 181 posts

Re: Useful and useless code comments

#111

Post by Jetrel »

mattacular wrote: post #50
emodendroket wrote: post #47

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.

Having had a lot of experience myself, I sadly can't echo this. A lot of it has to do with stick-and-carrot incentivization, stack ranking, and other stuff.

Unfortunately every place I've worked at sort of accidentally pits their programmers against each other in a sort of "who can get it done first" competition, with those who do a quick-and-dirty job getting credit, and those who clean up their proverbial workbench getting none. We've had gentlemen's agreements to not do this, and have even been able to collectively oust (i.e. get fired) a few serial violators, but there's just SUCH pressure to ship quickly that code review is basically a fictional thing like the flying spaghetti monster.

It's telling that we've got a MLOC codebase, and basically not a single piece of documentation - and every single place I've worked, in almost 2 decades, has been exactly like this.

Enterprise software is a wild ride. :|

Re: Useful and useless code comments

#112

Post by dagw »

jaggederest wrote: post #12

This is also somewhat about language choice. Languages more oriented towards natural language need less commenting. If I were writing C++ or assembler on a regular basis, I would probably be writing a lot of "what" comments. My favorite comments are actually "what" comments, but that clarify something opaque about the code, e.g. const R = 6371e3; const φ1 = lat1 * Math.PI/180; const φ2 = lat2 * Math.PI/180; const Δφ…

You're missing another potentially really important part in the comment. Why you chose to use the Haversine distance formula. Since you seem to be calculating the distance between two points on Earth it would be really useful to have a comment like

  // Vincenty algorithm too slow for our use case 
  // and we don't need that level of accuracy.
to make it clear that using Haversine was a conscious choice rather than the first answer you saw on the first question you looked at on Stack Overflow :)

Re: Useful and useless code comments

#113

Post by tomgp »

rectang wrote: post #57
benhoyt wrote: post #22

Earlier quoted context omitted.

Yeah, I like the "visual boundaries" way of framing it. A line of whitespace is a visual boundary, of course, but I find the // comment above it acts as a heading. Like a bold heading above a couple of paragraphs of text in a document. I wouldn't add a heading above every paragraph, but I would might above every few paragraphs. In code, this translates to every 5-15 lines of code. Here's some code I wrote recently th…

I know this style by the name "coding in commented paragraphs". I learned about it from Damian Conway early in my career, and the idea resonated with me so strongly that I immediately adopted it and have used it every since. I especially appreciate how under syntax highlighting the comments provide a visually offset natural language outline or summary of the code.

i use this method too. my flow is typically to write the comments first then implement them. this makes it easy to find gaps in reasoning before i write code and then easy to extract functions after if things get mor involved than expected.

Re: Useful and useless code comments

#114

Post by ithinkso »

benhoyt wrote: post #22
whoisjuan wrote: post #5

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…

Yeah, I like the "visual boundaries" way of framing it. A line of whitespace is a visual boundary, of course, but I find the // comment above it acts as a heading. Like a bold heading above a couple of paragraphs of text in a document. I wouldn't add a heading above every paragraph, but I would might above every few paragraphs. In code, this translates to every 5-15 lines of code. Here's some code I wrote recently th…

I like this a lot and I also use this. Comments as a narrative - you may quickly scan the function and read only 'headlines'-type of comments and if they are good, not too verbose, not too sparse, you have all the information needed. Combine it with a bit more descriptive summary at the beginning and and it's a pleasure to read and you immediately know where are the parts of interest. Reading pure code, even with the crazy enterprise style verbose function names is much harder and takes more time you need to waste on parts that in the end don't matter for the case you're looking for

Re: Useful and useless code comments

#115

Post by ithinkso »

manojlds wrote: post #69
whoisjuan wrote: post #5

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 my opinion there are two approaches to the idea of a function

Some use it as a method to separate code into independent, concise blocks that represent a singe step in a larger algorithm. Do one thing and do it well.

The other is code reuse, if a function is not reused in other places why create it at all? That's the reason for preferring comments rather than fragmenting code into add_vertical_scrollbar() functions. It's easier to read from top to bottom instead of jumping all over the place

Re: Useful and useless code comments

#116

Post by tempodox »

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 is much cheaper and faster and can be done while scrolling through it without stopping. If you can make that comment so it's more useful beyond that, so much the better.

Tricks like that come into play once you're past the language proficiency / commenting policy hurdles and feel the impact of your visual code design on your personal attention and energy budget.

Re: Useful and useless code comments

#117

Post by dragonwriter »

professor_v wrote: post #100
manojlds wrote: post #69

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.

A function makes the higher-level flow more clear and uncluttered than without either the function or comment, a comment may make it more clear but also makes it more cluttered.

> 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 to read.

Yes, function names should be extremely clear. But less code is easier to read than more code, so unless the contents (rather than the purpose) of the block of code is likely to be important every time you read the containing bit of code, you make the containing bit of code more readable by extracting the block.

> more lines of code, a comment adds 1 line while a function or method adds at least 4.

Depends on the language. In JS, for instance, a function definition can be a single line, so definition + call adds a minimum of 1 line, just like a comment. But a comment adds 1 line to the parent block of code, abstracting out a function at worst simplifies a single line, and usually reduces the lines of code in the parent block. So where the parent but not the content of the abstracted bit is important, it reduces code read, whereas the comment always increases it.

> Naming issues, it can be hard to think of a good name for a function and it almost never describes it perfectly.

Whether you can think of a clear name for the function is, IMO, part of the test for whether it is a logically coherent unit of work to abstract out to a function in the first place.

> Comments have the luxury of potentially conveying more information and are also less important to get right.

Comments are a pure addition of clutter to the code they are attached to; if they aren’t gotten right they are not just visual noise but misleading visual noise. Comments are no less important to get right than naming of functions.

Re: Useful and useless code comments

#118

Post by rectang »

tomgp wrote: post #113
rectang wrote: post #57

Earlier quoted context omitted.

I know this style by the name "coding in commented paragraphs". I learned about it from Damian Conway early in my career, and the idea resonated with me so strongly that I immediately adopted it and have used it every since. I especially appreciate how under syntax highlighting the comments provide a visually offset natural language outline or summary of the code.

i use this method too. my flow is typically to write the comments first then implement them. this makes it easy to find gaps in reasoning before i write code and then easy to extract functions after if things get mor involved than expected.

FWIW, I don't really do that. Sometimes I write the comments as I go; there is almost always a pass I make at the end as I'm preparing the material for review where I revise the existing comments and add missing ones.

I mention this because I think it's great that the commenting style works with both our workflows and doesn't really imply rigid adherence to either one of them. I suspect we would find it comfortable to maintain each others' code despite the divergence in approach.

Re: Useful and useless code comments

#119

Post by citrin_ru »

dragonwriter wrote: post #117
professor_v wrote: post #100

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. A function makes the higher-level flow more clear and uncluttered than without either the function or comment, a comment may make it more clear but also makes it more cluttered. > Unless the function is extremely clear like max() or min(), you will have to read the function and jump around the code. I feel peop…

> A function makes the higher-level flow more clear and uncluttered

It is subjective and depends on a given piece of code. In my experience functions (abstraction in general) often obfuscate code, because you cannot really see what they do without jumping to another place and breaking a flow of reading.

There are of course cases where factoring a piece of code into a function would make in more readable, but I cannot say this about any group of commented lines. And a function requires a comment too.

Re: Useful and useless code comments

#120

Post by dmurray »

rflrob wrote: post #93

I find the choice of the phrase “¿Como te llamas?” fascinating as evidence against “don’t do translation word for word in your head. ” Taken literally, “how (como) you (te) are called (llamas)” has no words in common with “what is your name”. The comments in the code would allow someone with a good Spanish vocabulary to actually translate into fluent English.

Yeah, it makes the complete opposite point of what the author is trying to say. Even as a beginning Spanish student, he didn't translate Spanish word-by-word, but phrase-by-phrase.
Post reply on HN