Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Stop commenting your code just to say you did

bradt.ca

Post reply on HN
Print view View original

11–20 of 76 posts

Re: Stop commenting your code just to say you did

#11

Post by fournm »

wdewind wrote: post #5
nghst wrote: post #3

I think the occasional "header" comment is useful, even in cases where the code is obvious, i.e. // do blah blah obvious_thing; obvious_thing; obvious_thing; obvious_thing; // do something else obvious_thing; obvious_thing; obvious_thing; obvious_thing; Even though none of the lines really need documentation, having the comment ensures that you can quickly jump in when you come back later. This is really useful in so…

Here's a better solution: function main() do_blah_blah(); do_something_else(); end function do_blah_blah() obvious_thing; obvious_thing; obvious_thing; obvious_thing; end etc..

This isn't always possible in every case--it's not too hard to imagine a lot of trivial assignment all going on at once, that isn't immediately obvious what it is or why on earth it exists.

  //really bad example, just something really repetitive
  function main()
    // set up month boundaries
    janStart = blah;
    janEnd = blah;
    // ...
    decStart = blah;
    decEnd = blah;
  end
where it's not too hard to imagine many languages without great pointers needing to keep that inline to avoid making all of those variables global. In some (hopefully most) cases just better design in general can get around it, but I wouldn't always count it out immediately.

edit: oops, formatting fail.

Re: Stop commenting your code just to say you did

#12

Post by lmm »

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…

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

Re: Stop commenting your code just to say you did

#14

Post by wschroed »

jeremiep wrote: post #8
wdewind wrote: post #5

Earlier quoted context omitted.

Here's a better solution: function main() do_blah_blah(); do_something_else(); end function do_blah_blah() obvious_thing; obvious_thing; obvious_thing; obvious_thing; end etc..

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, comments often do.

Description function names lie just as much as comments. For example, I have run into cases in the wild where things like "get_item()" create database entries before returning a value. Yes, side effects are evil, etc etc, but the point is that at some point, somebody maintained the code and did not update every use of get_item() to now be get_and_or_create_items_if_it_is_sunday(). In rare cases, I have seen them at least update the local documentation.

Re: Stop commenting your code just to say you did

#15

Post by collyw »

jeremiep wrote: post #8
wdewind wrote: post #5

Earlier quoted context omitted.

Here's a better solution: function main() do_blah_blah(); do_something_else(); end function do_blah_blah() obvious_thing; obvious_thing; obvious_thing; obvious_thing; end etc..

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

What's to say a function gets "fixed" without updating the name, in the same way that comments will not get updated? I see it would be less likely in a function, but not impossible.

Re: Stop commenting your code just to say you did

#16

Post by logfromblammo »

My current employer makes the useless code comments mandatory. They do not need to make sense or be useful; the requirement is that they exist. Fortunately, they pay me enough that I am not looking for other jobs over it.

No, I'm looking elsewhere due to the many other aggravations that are not worth the salary.

Not only are businesses training younger developers to do this, but they are training older developers to expect it. Of course it is going to bleed over into the real world.

Re: Stop commenting your code just to say you did

#17

Post by [deleted] »

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.

[deleted]

Re: Stop commenting your code just to say you did

#18

Post by pekk »

ef4 wrote: post #2

This is one of the reasons that programmers who haven't read much of other people's code are a liability. They're as lost as novelists who don't read books. The difference comes down to empathy: if you can get inside the head of your future readers, you'll know when to comment, and what to name that function, and how long the functions should be, etc...

So can we say the same about people who try to lobby everyone not to use any comments just in case they might be wrong? Because a helpful comment can be a very helpful thing to a reader of code

Re: Stop commenting your code just to say you did

#19

Post by pekk »

logfromblammo wrote: post #16

My current employer makes the useless code comments mandatory. They do not need to make sense or be useful; the requirement is that they exist. Fortunately, they pay me enough that I am not looking for other jobs over it. No, I'm looking elsewhere due to the many other aggravations that are not worth the salary. Not only are businesses training younger developers to do this, but they are training older developers to…

If they were paying you in part to make adequate documentation (which might well include good code comments) I wouldn't see any problem

Re: Stop commenting your code just to say you did

#20

Post by hjnilsson »

lmm wrote: post #12
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…

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 to functions, which means the codebase ends up with useless javadoc-like clutter.

It's the same with "100% test coverage", which is similarly abused, programmer's are a lazy bunch, and smarter than any tool that measures the quality of what they do. So forcing them doesn't work out great.

Post reply on HN