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

161–170 of 181 posts

Re: Useful and useless code comments

#161

Post by thrwaeasddsaf »

drran wrote: post #144
thrwaeasddsaf wrote: post #125

Earlier quoted context omitted.

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.

I haven't seen a tool that can remove fluff and clean code. And I don't like formatters, because making the rules right is too complicated. I haven't seen a formatter that won't eventually mess up code that I carefully laid out.

Re: Useful and useless code comments

#162

Post by ArtDev »

I wrote obvious comments to obvious code. No one else looks at my code but I do, a lot. The result is easy navigation of many many lines of code. The comments act as an index and summary to each section.

When it comes to comments, be verbose!

Re: Useful and useless code comments

#163

Post by toomanybeersies »

I agree in principle. If it takes more than more than a second to grok what a particular bit of code is doing, it should have a comment (or be extracted into a method).

However, in my experience, it's common for either:

1. Code to get changed, but the relevant comments are unchanged, or

2. Comments that are just as hard to understand as the code

In both cases, it's even harder to understand the comment+code than if there was no comment at all

Re: Useful and useless code comments

#164

Post by tharkun__ »

nerdponx wrote: post #63
tharkun__ wrote: post #36

Earlier quoted context omitted.

I don't really get why your mental model is bothered more by the function/stack frame than the comment. Whether I read a function name or comment personally that does pre occupy my mind and sets the mental frame for what comes next. If the comment or function name say doX() or //this does X then I expect it to do that but need to be on the lookout for whether it actually does that. With a function though I can easily…

Stepping in and out is an extra step, mentally and physically. It's increased burden on my working memory, which is usually already quite full keeping track of other aspects of the task at hand. Also it imposes more burden on the author, and possibly could lead to developing the wrong abstraction, which we all know is bad.

I don't get that. If you need to step over a function call you just remember 'oh right, step over doZ()' vs 'oh right this is 78 lines in which the code does Z, and dang I'm stepped 24 lines into it already before noticing. Where was the end of this again so I can skip ahead?'

One of those seems easier to me. Potentially our brains just work way differently but I have a much easier time remembering that function name I will step over.

Re: Useful and useless code comments

#165

Post by wruza »

ignoramous wrote: post #158
drran wrote: post #143

Earlier quoted context omitted.

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

False equivalence. That said, I agree with both OP and GP. I personally prefer clarity take precedence over whatever code-commenting or code-formatting guidelines one might have in place. It is all about common sense, I guess.

If a sense is discussed by camps with opposing opinions, it is far from common by definition.

A better analogy I think would be legal contracts with no headers and no numbered/bullet points. Headers in bold text have no value in a court, why not simply have a few pages of plain text that is self-explanatory? Also applies to comments to laws and religious texts.

I personally prefer clarity should take precedence over

Many programming interfaces are designed with no clarity in mind, sadly. Also many processes are not so straightforward and contain intermixed logic, like (0) get a raw request (1.a) get this, (2.a) get that, (3) log raw event with half-assed data for monitoring or debugging, ((1,2).b) check both and throw, (4) combine into a task, (5) log task, (6) proceed further. This creates zigzags in the code flow that you can’t reduce by abstracting things away, because it would blow up a complexity to insane levels.

I agree that on one hand micro commenting is dumb, but if your blocks are 3-4-line long it’s usually a sign of good structure, which is unrelated to commenting itself. A good structure is self-explanatory, but its flow may be complex (ask Brooks). Human attention-switching helpers seem useful to me, because they help seeing the flow. A short comment on what’s going on is like an inlined IIFE without accompanying visual/scope clutter.

Re: Useful and useless code comments

#166

Post by mattacular »

emodendroket wrote: post #148
mattacular wrote: post #50

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.

I guess I have been lucky but I don't really get this. You read comments along with the actual code right? They complement one another. An out of date comment should not ipso facto render code indecipherable and if it does that speaks to a bigger problem with the code itself.

I find it strange that people want to throw the baby out with the bathwater when it comes to commenting code just cause they've been bit before.

Re: Useful and useless code comments

#167

Post by wruza »

kwinten wrote: post #76
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()

Careful, you might trigger about half of HN with your proposal of readable code and small functions. This is literally always the right answer. Create a self-explanatory function or just use readable variable names. Or even createScrollbar(Direction.VERTICAL) if you hate repeating yourself.

Now instead of a bunch of prepared and labeled dishes you have an API border in the middle of your kitchen, which of course will greatly help at slight changes in the menu. When in doubt, just pepper it with more enums and boolean flags. /s

Re: Useful and useless code comments

#168

Post by Izkata »

js8 wrote: post #55
tharkun__ wrote: post #35

Earlier quoted context omitted.

I think this is a question of level of abstraction. I would argue that that this more readable as for what is going on: addHorizontalScrollbar() ; addVerticalScrollbar(); addHeader(); addDayColums(); addFooter(); If all I need to know is how the page is structured and set up on a high level, then this is awesome (actually I'm not convinced it needs the scroll bar stuff on this level but this was what I could come up…

This might be more readable if setting up those things doesn't involve a set of common variables (say a GUI style in this example) that can affect them. If it does, then you have to pass them around (into these functions) and it makes more difficult to figure out, if one of these variables changes, what all is affected by it (you have to look up all those methods). In short, I don't think adding depth to a hierarchy…

I think it makes the source of such a styling bug/flow of what's affected a lot more obvious than having to find the reference in each line of the implementation details:

  addHorizontalScrollbar($style);
  addVerticalScrollbar($style);
  addHeader();
  addDayColums($style);
  addFooter($style);

Re: Useful and useless code comments

#169

Post by emodendroket »

mattacular wrote: post #166
emodendroket wrote: post #148

Earlier quoted context omitted.

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

I guess I have been lucky but I don't really get this. You read comments along with the actual code right? They complement one another. An out of date comment should not ipso facto render code indecipherable and if it does that speaks to a bigger problem with the code itself. I find it strange that people want to throw the baby out with the bathwater when it comes to commenting code just cause they've been bit before…

You don’t see how you could end up wasting time when a comment led to you making an incorrect assumption? If they don’t affect how you read the code would mean they’re useless.

Re: Useful and useless code comments

#170

Post by pineconewarrior »

HerrMonnezza wrote: post #132
pineconewarrior wrote: post #131

Earlier quoted context omitted.

I tried to find more information on this by searching for those terms and "damian conway" but came up empty. Would you mind sharing a link, if you have one?

Not sure if there's anything written on the topic, but I guess you can take a look at some of Damian Conway's public code to see it being used. For example: https://metacpan.org/release/DCONWAY/Keyword-Declare-0.00101...

Thank you for the link. I'll check it out!
Post reply on HN