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

31–40 of 181 posts

Re: Useful and useless code comments

#31

Post by tylorr »

whoisjuan wrote: post #27
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…

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.

Re: Useful and useless code comments

#32

Post by shusaku »

tharkun__ wrote: post #29
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 Δφ…

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

Re: Useful and useless code comments

#33

Post by tablespoon »

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…

> The big problem with comments is that they need to be maintained. When the code changes, the comments need to change with it.

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

When you think about it, function and variable names are comments. Should we not use those because they need to be maintained with the code?

Re: Useful and useless code comments

#35

Post by tharkun__ »

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 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 with to stay in the example :) ) I don't need to read comments for what's what and then manually skip over ever so many lines of actual code that did all these things. I can decide that what I really wanted to take a closer look at was what the header bar looks like.

Some of this depends on whether I'm using an IDE or not. In an IDE I can just Ctrl click myself through. Then again I doubt anyone these days is using _just_ vi to code something complex enough to want multiple files. I used vi configured as an IDE way back but I do admit that's been like 15 years. Dunno what that looks like today. Nowadays I'm a JetBrains user, mainly in Java and Java/TypeScript and very little Python.

Re: Useful and useless code comments

#36

Post by tharkun__ »

UglyToad wrote: post #14
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()

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 step out if this part turns out not to be interesting, I can easily step over it next round if debugging, I don't need to keep track of where //this does X ends etc.

Of course none of these help if the previous author was really bad at what they were trying to communicate. They can both implement doY() in a function called doX() and have //do Y code run in with //do X for example by interleaving statements for both. If we assume we'll intentioned authors for both though, I would tend to see more pros for structuring code with functions than via comments.

Re: Useful and useless code comments

#37

Post by flukus »

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()

This sounds perfectly reasonable in isolated examples, but I find maintaining large applications written in this style to be a nightmare. Once you get to non-trivial examples you'll have a lot of variable being passed around (what are we adding the scrollbar too) and stepping through a million little functions to see which components are interacting and how.

The first example might need a comment, but everything I need to know is right there in one place and not distributed across the codebase.

Re: Useful and useless code comments

#38

Post by [deleted] »

mumblemumble wrote: post #18

The more I see people opine on commenting style, the more I want to just spam the "you do you" button and get on with my life. I have a way that I like to do it. Other people on my team have their own ways. My way is not hurting them. Their way is not hurting me. Either of us trying to impose our way on the other would hurt both of us.

[deleted]

Re: Useful and useless code comments

#39

Post by tharkun__ »

nitrogen wrote: post #10
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()

If you're building a UI frame, like in this Swing example, I think it's reasonable to keep the code in a single method and separate it into functional blocks with comments. But the variable names and comments should still include a bit more of the why . Example: // Build the data table view ... // Add horizontal scroll bar to the data table view // This is needed if the table has more than N columns tableHScroll = //…

Think about this. You intentionally left out the very verbose parts of actually doing those things for us to see what your UI looks like on an abstract level here on HN. You basically only gave us the comments and left out the 49 lines of actual code needed in between for each ...

With methods extracted you could do the exact same but on actual code and help your future self that forgot all about this class or some other poor developer that has never seen this UI or the code before.

Re: Useful and useless code comments

#40

Post by BurningFrog »

tablespoon wrote: post #33
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…

> The big problem with comments is that they need to be maintained. When the code changes, the comments need to change with it. > 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. When you think about it, function and variable nam…

My main solution is to use good function and variable names.

Including - and I had some resistance to this - breaking out a variable or function solely to give something a name that needs describing.

This way you have one source of truth. It can be wrong, but you only update it once, and it never conflicts with itself.

I understand what you mean by "function and variable names are comments". We do use them to describe what the code does. Still, they are actually code :)

Post reply on HN