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

151–160 of 181 posts

Re: Useful and useless code comments

#151

Post by chowderman »

Yaina wrote: post #134

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 s…

Same here, I think small comments every 3-10 lines adds a lot of value, especially to large code bases. Being able to quickly scan through comments visually when you only need a high level overview of a chunk of code can take a 5 minute task of reading and understanding 50 lines of code into a 15 second task of reading and digesting a few small comments.

Also, I'm curious to see how your experience was working on the firefox code base. I haven't checked out the code base myself, but have built from source a few times. Curious to see how the Rust progress has been going on the code base and which parts of firefox are currently implemented in Rust.

Re: Useful and useless code comments

#152

Post by emodendroket »

drran wrote: post #150
emodendroket wrote: post #148

Earlier quoted context omitted.

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

Consider reviewing of your code review process.

Code review can miss because the inaccurate comments might not be close enough to show up in the diff viewer

Generally if I see something happen in every job I've had throughout my career I start to doubt that there is a simple process solution.

Re: Useful and useless code comments

#153

Post by drran »

ping_pong wrote: post #66

I think it's stupid when people say they don't think code comments are good or necessary. It's a weirdly religious debate and frankly I think having a ton of code comments is great. Some of my closest friends think that all comments are absolutely unnecessary. We didn't work in the same code repos. I think 2 IDE features would make things easier for everyone: 1) have an option to remove code comments from view if you…

1) Early versions of UNIX were shipped in source form with code comments stripped, for better readability and maintenability of the code. Google "obfuscation".

2) IMHO, it's better to assign a premium for the comment fix at GitHub. Your time is expensive, so it's better to outsource this distracting task to someone in India, because English is the official language in India. And track all that via a smart contract on a blockchain.

Re: Useful and useless code comments

#154

Post by rectang »

IlliOnato wrote: post #140
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?

"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 nee…

I found a page which excerpts 10 of Conway's recommendations from Perl Best Practices (which I no longer have around). Point 7 is "Code in Commented Paragraphs", and the reasoning is about what I remember — it might even be taken from the book verbatim:

https://www.perl.com/pub/2005/07/14/bestpractices.html/#7-co...

There are other recommendations on that page and in Conway's highly opinionated book which I disagree with (it's notorious for recommending Class::Std), but that point has stuck with me.

Note that Conway's example even includes three single-code-line paragraphs, all of which are commented. Perhaps Osterhout would not approve, or perhaps he would — each of those lines includes some subtlety, and each of the comments describes the "why" not the "what".

FWIW I don't always add a comment above single line paragraphs if the comment adds nothing. But neither does Conway comment "unpack arguments" above the first line in his example, nor say anything about the return statement — which to my mind illustrates that there's some flexibility to be expected in how you apply this technique.

Re: Useful and useless code comments

#155

Post by drran »

emodendroket wrote: post #152
drran wrote: post #150

Earlier quoted context omitted.

Consider reviewing of your code review process.

Code review can miss because the inaccurate comments might not be close enough to show up in the diff viewer Generally if I see something happen in every job I've had throughout my career I start to doubt that there is a simple process solution.

Confirmed.

We found a problem! Let start a startup: "Intelligent code review tool for smart developers, which want to keep comments in their code up to date". The tool will use AI to learn which parts of code are modified often in unison, and then propose to check them also during code review. It will also check for copy-pasted code blocks, and for snippets from StackOverflow with known bugs. The tool will reduce code review time by 10%, reduce number of bugs slipped trough code review by 20%, improve time to ship by 7%, bla bla bla, and instruct the coffee machine to prepare a coffee just in time for the review.

Re: Useful and useless code comments

#156

Post by dragonwriter »

citrin_ru wrote: post #119
dragonwriter wrote: post #117

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

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

Already discussed in the post you are responding to: “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.”

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

Also already addressed, e.g.: “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.”

> And a function requires a comment too.

Not necessarily. A function in the public interface of a module probably needs a doc comment or docstring, but we’re discussinf abstracting out a piece of functionality used once, so presumably this is to a private function in the same module, not part of the public interface of the module.

Re: Useful and useless code comments

#157

Post by Yaina »

chowderman wrote: post #151
Yaina wrote: post #134

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 s…

Same here, I think small comments every 3-10 lines adds a lot of value, especially to large code bases. Being able to quickly scan through comments visually when you only need a high level overview of a chunk of code can take a 5 minute task of reading and understanding 50 lines of code into a 15 second task of reading and digesting a few small comments. Also, I'm curious to see how your experience was working on the…

Firefox is still largely C++ and Javascript and that's not going to change anytime soon. But it makes sense, because mostly you're adding or changing stuff that's already deeply connected with all the existing code.

I think you see Rust when there are really big projects that can be treated as a library. For instance the network team is writing their QUIC implementation in Rust – called neqo – and I can imagine that this was possible because it's low level enough and separate enough from the rest of Firefox.

It's of course also a resourcing question. For instance the download-manager code in Firefox is a big, big mess and it's not really owned by anyone. But it works, is safe, and handles a lot edge cases. Rewriting this thing (even again in Javascript) would be an enormous effort, and that's true for so many parts of the code base that might benefit from rewrites. A rewrite would be nice, but there probably will always be more important things to work on.

Re: Useful and useless code comments

#158

Post by ignoramous »

drran wrote: post #143
incrudible wrote: post #130

Earlier quoted context omitted.

> But you cannot expect everyone to have the same proficiency you do. Writing good code, also means writing code that a newbie can at least comprehend. If you're writing example code or documentation, by all means, add this kind of comment. Otherwise, if someone can't comprehend these particular two lines without reading the comment, they need to get back to the drawing board. You can't have noisy code like that in p…

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.

Re: Useful and useless code comments

#159

Post by ptx »

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…

I tend to agree that sections headings are OK (although it might be better to extract the sections to separate functions) but some people take it further than that.

Today I ran into this piece of code:

  // POST
  xhr.open("POST", "...");
  // Content-Type
  xhr.setRequestHeader("Content-Type", "...");
  // SOAPAction
  xhr.setRequestHeader("SOAPAction", "...");

Re: Useful and useless code comments

#160

Post by [deleted] »

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.

[deleted]
Post reply on HN