Stop commenting your code just to say you did • Hacker News Board

Re: Stop commenting your code just to say you did

#21

Post by ebiester » Tue, Apr 01, 2014, 4:59 PM UTC

carsongross wrote: post #7

God forbid someone gets their thoughts together with comments outlining what a function is going to do and then fills in the code... Or, while deep in thought, someone taps out a bit of redundant commentary on a line or two of their code... Or someone needs a bit of natural language to provide an anchor in their code. The important thing here, I think we can all agree, is that we are smarter than that person.

Not at all. I use comments like this frequently.

It might even be checked in while development is happening.

However, the "whats" are taken out completely - the tests are better places to figure out how it works, anyway. The "hows" are mostly taken out -- if someone needs to know how it's working, it needs to be refactored. (And that's why I wrote the tests!)

What remains are the "whys." Why was this algorithm chosen? Why does this look seemingly broken? Why is this code here? (IE, performance improvement led to a little less clean code.)

Re: Stop commenting your code just to say you did

#22

Post by SomeCallMeTim » Tue, Apr 01, 2014, 4:59 PM UTC

Danieru wrote: post #9

I suspect part of this is enforced by TA markers in university. When marking a TA isn't trying to understand the code, they just do not have time for that. So when evaluating the documentation or comments portion of the mark they just scroll through and see how much gray is on their screen. No marks are ever deducted for bad comments. The situation can get so silly I've had TAs complement my code and the design then…

I've argued my way out of TAs downgrading me because of comments, when the comments I DID have conceptually covered several lines of source code (and they were looking for a comment on each line).

Re: Stop commenting your code just to say you did

#23

Post by jeremiep » Tue, Apr 01, 2014, 5:00 PM UTC

masklinn wrote: post #10

jeremiep wrote: post #8

Earlier quoted context omitted.

It should be pointed out that with inlining, both versions are exactly the same at runtime. Descriptive function names never lie, comments often do.

> Descriptive function names never lie Beg pardon[0]? function _utf8Encode(&$arr){ for($i=0;$i Or[1] public static string ReturnEmptyStringIfNullElseValue(string value) { if (value == null) { return ""; } else { return value.ToString().Trim(); } } [0] http://thedailywtf.com/Comments/There-and-Back-Again.aspx [1] http://thedailywtf.com/Articles/Common-Functions,-not-Common...

I stand corrected. Thank god I never have to deal with such code!

Re: Stop commenting your code just to say you did

#24

Post by swanson » Tue, Apr 01, 2014, 5:02 PM UTC

carsongross wrote: post #7

God forbid someone gets their thoughts together with comments outlining what a function is going to do and then fills in the code... Or, while deep in thought, someone taps out a bit of redundant commentary on a line or two of their code... Or someone needs a bit of natural language to provide an anchor in their code. The important thing here, I think we can all agree, is that we are smarter than that person.

    // don't use hardware acceleration
    canvas.enableHardwareAcceleration(true);

Which is true? The comment is lie. Is this a bug? Was this changed for some reason? Should I remove the comment? Should I toggle the boolean? Why weren't we supposed to use HW acceleration? Why are we using it now? What changed? What value did the comment have in the first place?

Re: Stop commenting your code just to say you did

#25

Post by SomeCallMeTim » Tue, Apr 01, 2014, 5:04 PM UTC

The example that he gives that I take issue with is the "Constructor" one in a JavaDoc comment.

When using documentation tools, every undocumented function spews a warning. And that is as it should be. But some simple constructors don't have any functionality worth documenting.

I code as if all warnings should be addressed, and that's true of my documentation generation. If a public function has no documentation, that should be considered an error that needs fixing. If the documentation is obvious, then so be it.

That is the price you pay for reliably good documentation; without enabling those warnings you don't know when you've missed documenting an important function. And even sometimes the "obvious" is useful; I don't know how many ambiguous Boolean parameters I've seen where it wasn't clear what value "true" represented.

Re: Stop commenting your code just to say you did

#26

Post by quackerhacker » Tue, Apr 01, 2014, 5:06 PM UTC

Comments in production code have always been a pet peeve of mine. I understand the OP's frustration on useless comments where the function clearly states enough in it's naming convention.

I brought this up to one of my instructors before and he said that comment overhead is negligeble on bandwidth (I was referring to css and js commenting at the time), but I don't think that's true when you factor in mobile networks and when some teams comment every freaking line when naming convention and common sense should suffice.

Re: Stop commenting your code just to say you did

#27

Post by Ellipsis753 » Tue, Apr 01, 2014, 5:08 PM UTC

swanson wrote: post #24

carsongross wrote: post #7

God forbid someone gets their thoughts together with comments outlining what a function is going to do and then fills in the code... Or, while deep in thought, someone taps out a bit of redundant commentary on a line or two of their code... Or someone needs a bit of natural language to provide an anchor in their code. The important thing here, I think we can all agree, is that we are smarter than that person.

// don't use hardware acceleration canvas.enableHardwareAcceleration(true); Which is true? The comment is lie. Is this a bug? Was this changed for some reason? Should I remove the comment? Should I toggle the boolean? Why weren't we supposed to use HW acceleration? Why are we using it now? What changed? What value did the comment have in the first place?

It's a pain but check the git history.

Re: Stop commenting your code just to say you did

#28

Post by millstone » Tue, Apr 01, 2014, 5:11 PM UTC

Don't listen to this guy. Copious comments are great.

1. They act as a easier-to-skim narrative of the code. You can often get an outline of a well-commented component by reading the comments alone, rather than by picking apart a language designed for machine consumption. Syntax highlighting makes this especially easy.

2. They're helpful for other programmers who may not be as comfortable in the language as you are. For example, my PHP is about ten years old; I had no idea that `__construct` is the constructor, and not just another function. But thanks to the "useless" comment, I do know that.

3. They're helpful for programmers who aren't as comfortable in the problem domain. A line in a FFT implementation may be "obvious" to those skilled in harmonic analysis, but not the poor client programmer who is trying to figure out why the function is returning garbage output.

4. They can be useful as a thing to search for when you need to navigate around.

When deciding if I should write a comment or not, I ask myself a simple question: if I come back to this bit of code, will it be obvious why it’s been written this particular way? If my future self will be very thankful for an explanation, then it’s a no brainer, I write the comment.

Note the assumption that the code will only be consumed by "my future self".

Ever maintained someone else's under-commented or no-commented code? I'm sure the original programmer did not have any trouble with it, and will never know what he inflicted on his successors. Spend some time working in a comment desert, and you'll never complain about the rain.

Re: Stop commenting your code just to say you did

#29

Post by swanson » Tue, Apr 01, 2014, 5:11 PM UTC

Ellipsis753 wrote: post #27

swanson wrote: post #24

Earlier quoted context omitted.

// don't use hardware acceleration canvas.enableHardwareAcceleration(true); Which is true? The comment is lie. Is this a bug? Was this changed for some reason? Should I remove the comment? Should I toggle the boolean? Why weren't we supposed to use HW acceleration? Why are we using it now? What changed? What value did the comment have in the first place?

It's a pain but check the git history.

Both lines were committed at the same time in a changeset with 15 other files. What now?

Re: Stop commenting your code just to say you did

#30

Post by untog » Tue, Apr 01, 2014, 5:13 PM UTC

hjnilsson wrote: post #20

lmm wrote: post #12

Earlier quoted context omitted.

It's not just markers at university, I've had managers who would do the same thing.

Working as a contractor, there are often deals that mandate "100% of functions documented" or other silly stuff (I would never strike such a deal, but have inherited projects with this). Since the client actually never checks the code (only metrics) and will never pay what it would cost to create amazing documentation (which only makes sense for public APIs) we just end up with tools that automatically adds comments…

Working as a contractor, there are often deals that mandate "100% of functions documented" or other silly stuff

I'm not so sure that's silly. It's absolutely overkill, but in a contractor/client relationship it makes sense that the client will want to make sure they have all the coverage they can get. And as a contractor you can bill for it.