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

51–60 of 181 posts

Re: Useful and useless code comments

#51

Post by jkrubin »

Something I don't see mentioned at all is what I call 'div comments' which are solely for chunk organizing. I use something like the following quite a bit (in python/bash):

  # =============================================================================
  # /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/
  # =============================================================================
Doesn't give any hints about the codebase but (at least to me) it lets me see related blocks.

Re: Useful and useless code comments

#52

Post by sircastor »

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 just used this formula in code this last week, and I thought “hey, I recognize that!”

Re: Useful and useless code comments

#53

Post by leetrout »

jkrubin wrote: post #51

Something I don't see mentioned at all is what I call 'div comments' which are solely for chunk organizing. I use something like the following quite a bit (in python/bash): # ============================================================================= # /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/ # ============================================================================= Doesn't…

Sometimes a smell you should use multiple files or classes.

Re: Useful and useless code comments

#54

Post by ajarmst »

When I teach coding, I used to have a similar lesson around commenting code: "don't tell me you're creating a variable. I can read the code. Tell me what the variable is for."

I still mostly abide by that, but I've had an opportunity to write some larger programs for the first time in a few years (a hazard of teaching programming is you find yourself working with pretty small programs), and noticed that the comments started become a part of my conversation with myself. I'd drop in quick reminders for what I intended to do in a function before going moving on to something else. When I came back and then wrote the code corresponding to the comments: well now it's redundant, but it wasn't. I stopped cleaning that stuff up (I'd clean it if I had to present or publish it, of course). The comments kept some context of my thinking when I wrote it, what order I did things in, etc. It would be gibberish for another, but it wasn't for me, especially after a few days, or even longer. (Note: I'm a pretty fast touch-typist, so muttering to myself doesn't invoke much of a productivity cost. I also note that commit messages are another great place to capture that sort of context for yourself, and not using that opportunity is a sin.)

So, I've changed some of my greybeard aphorisms around commenting: "When commenting code, consider the needs of the person who will be maintaining this code. Who will probably be you. Be nice to future you."

Re: Useful and useless code comments

#55

Post by js8 »

tharkun__ wrote: post #35
mumblemumble wrote: post #15

Earlier quoted context omitted.

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…

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 of function composition is always an answer. Flatter hierarchies can be easier to understand too.

Re: Useful and useless code comments

#56

Post by fake-name »

jkrubin wrote: post #51

Something I don't see mentioned at all is what I call 'div comments' which are solely for chunk organizing. I use something like the following quite a bit (in python/bash): # ============================================================================= # /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/ # ============================================================================= Doesn't…

I use dividers like this because they're visible in the mini-map view that editors like sublime/vscode/atom have.

Re: Useful and useless code comments

#57

Post by rectang »

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

Re: Useful and useless code comments

#58

Post by longcommonname »

Someone1234 wrote: post #45

When I was doing CS in college, bad commenting was an academic requirement: As in your grade would be worse if you commented appropriately. Over multiple courses including software engineering, comment quality and or correct use of comments was never in the syllabus. But in several courses they wanted to see the code heavily commented, to the point where you were just re-writing the code as a comment and getting a gr…

How comments in school indicate to the grader that you not only can write code but you can explain what it's doing in another way.

It's actually a somewhat decent way to catch cheaters. As it provides a better likeness score between two code comparisons.

Re: Useful and useless code comments

#59

Post by perl4ever »

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…

>setting up those things doesn't involve a set of common variables

So...object methods?

Re: Useful and useless code comments

#60

Post by cutemonster »

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.

Also, function names sometimes get out of date too, 'addHorizontalScrollBar()' in the example above -- let's say someone adds vertical scroll too but forgets to update the function name.
Post reply on HN