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

131–140 of 181 posts

Re: Useful and useless code comments

#131

Post by pineconewarrior »

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 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?

Re: Useful and useless code comments

#132

Post by HerrMonnezza »

pineconewarrior wrote: post #131
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 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...

Re: Useful and useless code comments

#133

Post by kyranjamie »

These examples aren't great. Functions have names for a reason. Use them. Comments get outdated quickly, people forget/are too lazy to update them. Much less likely in my exp. that someone will not change a fn name if it's behaviour changes.

Comments should be reserved for non-obvious information. Github link, complex mathematics etc. Further, at what point does the relevance of a comment end? This ambiguity doesn't exist with a function.

    function addHorizontalScrollbar() {
      hScrollBar = new JScrollBar(scrollBar, HORIZONTAL);
      add(hScrollBar, BorderLayout.SOUTH);
    }

    function addVerticalScrollbar() {
      vScrollBar = new JScrollBar(JScrollBar.VERTICAL);
      add(vScrollBar, BorderLayout.EAST);
    }

    function initializeScrollbarCaretPositions() {
      caretX = 0;
      caretY = 0;
      caretMemX = null;
    }

Re: Useful and useless code comments

#134

Post by Yaina »

I'm a big fan of Short comments that describe a chunk of code – maybe 3-10 lines. Because a lot of times I don't really want to read all the code, I just want to get a more detailed sense of what the code is doing.

I worked in the Firefox codebase for a while, and what I would have given for a simple comment that describes intentions or results; where instead I had to fire up searchfox.org and make a deep dive into some (equally sparsely commented) functions.

There is some notion here, that these comments help new programmers, but I think as soon as your codebase is sufficiently big, there will be always parts you won't be familiar with, and these comments certainly help you scan over them quickly

Re: Useful and useless code comments

#135

Post by skohan »

> I find them useful as I write code because they allow me to state my intention (in plain English)

I have gone back and fourth on comments over the years, but currently I'm working on a solo project which has been in serious development for some time, and using comments in this way is really useful.

Especially because it's a domain I haven't done a ton of work in before, I've found my workflow is often to create a few source files, type out in comments what the component should do, and bit by bit hone in on how that should translate into code.

It's also great for placeholders: if I'm not ready to fill in an implementation yet, I can just type out a lengthy description in the function body, and when I come back a week later I can remember what the intent was.

Re: Useful and useless code comments

#136

Post by analog31 »

BurningFrog wrote: post #24

The big problem with comments is that they need to be maintained. When the code changes, the comments need to change with it. The never, ever happens consistently. So soon you have the "man with two watches" problem. The code says one thing, and the comments say another. You could fix it, and sometimes you spend that time, but inevitably you also stop reading the comments, since they're not reliable. I've never seen…

In my view there's no machine or rules that will automatically make your code readable against your will. If two people express themselves differently in prose, perhaps one better than the other, the same will be true in code, with or without comments.

Re: Useful and useless code comments

#137

Post by roland35 »

skohan wrote: post #135

> I find them useful as I write code because they allow me to state my intention (in plain English) I have gone back and fourth on comments over the years, but currently I'm working on a solo project which has been in serious development for some time, and using comments in this way is really useful . Especially because it's a domain I haven't done a ton of work in before, I've found my workflow is often to create a…

I do the same thing for any major block - write out steps 1) 2) and so on as comments to help keep the end goal in mind.

Re: Useful and useless code comments

#138

Post by juloo »

I always try to write a comment that say "why" the following code is needed or what concept it implements rather than what it does in details.

I would do

    // We allow scrolling in two directions
    hScrollBar = new JScrollBar(scrollBar, HORIZONTAL);
    add(hScrollBar, BorderLayout.SOUTH);
    vScrollBar = new JScrollBar(JScrollBar.VERTICAL);
    add(vScrollBar, BorderLayout.EAST);
    caretX = 0;
    caretY = 0;
    caretMemX = null;
(I don't have much inspiration in this specific example)

Re: Useful and useless code comments

#139

Post by UglyToad »

tharkun__ wrote: post #36
UglyToad wrote: post #14

Earlier quoted context omitted.

I think my problem with this approach and why I lean to favouring the more obvious and verbose comment is, if I'm reading the code it's probably because something is broken (or I need to change something in the area). With the function I think, "is it and if it is what else does it change?". Is that function definition actually doing what it says it is? So now I have to add another stack frame to my mental model, go…

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…

I think this probably relates to fundamental differences in how people think. Like the "imagine an apple" test of people's mental modes of imagination.

I'm quite a visual thinker so I use the shape of the surrounding code to anchor my mental model of the code. If I have to jump to another file or function then I lose the shape and it disrupts my model. This is why on balance I (now) prefer longer functions over code split up.

Re: Useful and useless code comments

#140

Post by IlliOnato »

pineconewarrior wrote: post #131
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 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?

"Coding in paragraphs" is described in Damian Conway's book "Perl best practices" [1]

Myself I like coding in paragraphs very much, and giving the paragraphs one-liner headings (comments) definitely makes code for me more readable and easier to navigate.

I usually don't give a heading to a "paragraph" which is just one line, unless that line does something subtle. (Conway provides a definition of "subtle": if you need to think more than 10 seconds or consult the fine manual to figure out what the line does).

[1] https://www.oreilly.com/library/view/perl-best-practices/059...

Post reply on HN