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

101–110 of 181 posts

Re: Useful and useless code comments

#101

Post by dagw »

LukeShu wrote: post #44
shusaku wrote: post #32

Earlier quoted context omitted.

The name of the function won’t necessarily reveal the algorithm used in the implementation

Yeah. I'd name the function something like `earthDistance` or `sphereDistance`, and then still have the "what" comment saying "haversine distance formula" inside of the function.

If I had a program where calculating distance between points on earth was important and I had an API with a function called earthDistance, then knowing that it was actually calculating the Haversine distance would be vital knowledge, since that approach is known to give quite high errors and that I should avoid using that function if I care about accuracy.

Re: Useful and useless code comments

#102

Post by sa46 »

mr_mitm wrote: post #79
aspaceman wrote: post #61

Earlier quoted context omitted.

Yup. I love this style of using code to create a "paragraph" of code with a section heading. You don't always want to separate out a function, but you do want the advantage of "titling" a section of code.

> You don't always want to separate out a function, Why not? The above could have easily contained a `ensureDirectoryExists(item)`. It would have the benefit of being more reusable, too.

An earlier submission has a lively debate between these two approaches. https://news.ycombinator.com/item?id=12120752

Re: Useful and useless code comments

#103

Post by tester34 »

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…

and that's how we created $company_framework/lib, I guess?

Re: Useful and useless code comments

#104

Post by NicoJuicy »

b93rn wrote: post #99
uberswe wrote: post #97

I spend a lot of time reviewing code, I currently review every line of code for 16 other developers. Obvious comments are great for code reviews because it's a validation that what you intended to do is what your code actually does. From the article, the comment about adding a vertical scroll bar allows me to review the code and to check that it does indeed add a vertical scroll bar and not something else. Did the de…

Great, but that's not the reason why obvious comments are bad. They are bad because it's not maintainable. For you this means that the next time a developer refactors the code, you need to check if the comment is still accurate with the refactored intentions. I repeat, this is not maintainable! I love how the book Clean Code described it: "A comment is a failure to express yourself in code." There are situation they…

Clean code of a guide, not a requirement.

Eg. I like paragraphed comments, because you know what the next 5 lines will do and you can quickly skip to the part you need.

It's not always possible to have a method with only 5 lines. There are use-cases where you want a big method doing a lot of things together, because it's complex.

Eg. For a government project i needed to connect to the internal network for executing certain requests and all that logic was in one HttpProxyClass, shared between the api + service/deamon

Re: Useful and useless code comments

#105

Post by dagw »

tharkun__ wrote: post #41
shusaku wrote: post #32

Earlier quoted context omitted.

The name of the function won’t necessarily reveal the algorithm used in the implementation

By all means, if the specific algorithm isn't important I would totally be onboard with you in naming it after what the purpose is instead! Feels like the difference between inlining quicksort vs. calling quicksort() vs. calling sort(). In some situations you really are on a level where you need to know you are calling mergesort() and not quicksort() but some are fine with sort(). I doubt there are many examples of c…

It's actually worse than that. Mergesort and quicksort will at least eventually give the same answer (ignoring sort stability). When it comes to numerical approximations different algorithms can all give different answers. Picking the right one is always a balance between performance, stability and accuracy and the right answer often depends on what your input looks like and how sensitive to errors you are.

Re: Useful and useless code comments

#106

Post by watt »

uberswe wrote: post #97

I spend a lot of time reviewing code, I currently review every line of code for 16 other developers. Obvious comments are great for code reviews because it's a validation that what you intended to do is what your code actually does. From the article, the comment about adding a vertical scroll bar allows me to review the code and to check that it does indeed add a vertical scroll bar and not something else. Did the de…

These comments will rot and become confusing/misleading oh so quickly.

It's great that somebody is reviewing every single line of code and probably will catch it when folks modify the code but inevitably forget to update the comment, and it becomes out of sync - becomes misleading.

If the reviewing is not vigilant that's where you end up: you don't know what to trust, the comment or the code. And the code wins, so that _what_ and _how_ type of comment becomes a net negative.

Re: Useful and useless code comments

#107

Post by b93rn »

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…

Yes, this is bad. If it was not clear enough that this created a VScrollBar, then create a function CreateVerticalScrollBar(). Why? Well this does exactly the same as commenting the code, except that this can easily be renamed with your IDE if the code base changes. Comments will always be outdated, functions not.

Re: Useful and useless code comments

#108

Post by fbcpck »

leetrout wrote: post #53
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.

This is true, but sometimes it's not possible or awkward to do.

I find myself writing such separator comment blocks in userscripts quite a bit; and stylesheets where I do not have any tooling attached to it (e.g. mediawiki css).

Re: Useful and useless code comments

#109

Post by b93rn »

NicoJuicy wrote: post #104
b93rn wrote: post #99

Earlier quoted context omitted.

Great, but that's not the reason why obvious comments are bad. They are bad because it's not maintainable. For you this means that the next time a developer refactors the code, you need to check if the comment is still accurate with the refactored intentions. I repeat, this is not maintainable! I love how the book Clean Code described it: "A comment is a failure to express yourself in code." There are situation they…

Clean code of a guide, not a requirement. Eg. I like paragraphed comments, because you know what the next 5 lines will do and you can quickly skip to the part you need. It's not always possible to have a method with only 5 lines. There are use-cases where you want a big method doing a lot of things together, because it's complex. Eg. For a government project i needed to connect to the internal network for executing c…

If those 5 lines do so much that you can't scan it quickly, why is it not in a function? I don't understand, why so many people here have a hard time of understanding this here on HN. You can't trust that comment, you don't know if its outdated or not.

Update: I noticed you updated your comment.

So my reaction to your addition is that a class can always be abstracted to higher level. It will probably do to much at this point.

Re: Useful and useless code comments

#110

Post by uberswe »

watt wrote: post #106
uberswe wrote: post #97

I spend a lot of time reviewing code, I currently review every line of code for 16 other developers. Obvious comments are great for code reviews because it's a validation that what you intended to do is what your code actually does. From the article, the comment about adding a vertical scroll bar allows me to review the code and to check that it does indeed add a vertical scroll bar and not something else. Did the de…

These comments will rot and become confusing/misleading oh so quickly. It's great that somebody is reviewing every single line of code and probably will catch it when folks modify the code but inevitably forget to update the comment, and it becomes out of sync - becomes misleading. If the reviewing is not vigilant that's where you end up: you don't know what to trust, the comment or the code. And the code wins, so th…

I see the point. I guess our team just puts the barrier for "useful comment" a bit lower than most other teams. I work with software as a medical device products which has requirements for documentation. Some of this documentation is autogenerated from doc blocks and it is therefore part of the review to also review comments.

I understand that my situation will not reflect the average developer. But it is good to see both points of view.

Post reply on HN