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

I hate comments

timothyfitz.com

Post reply on HN
Print view View original

31–40 of 55 posts

Re: I hate comments

#31

Post by kevinpet »

fotbr wrote: post #28

Take it up with programming 101 instructors around the world, who beat it into their students' heads that "every line" / "every function" / "every class" etc needs comments, no matter how redundant or bad the comment was, because "good code is commented". No joke, fairly well respected science & engineering university, every line of every program through the first three semesters of a CS program was required to be co…

Really? Find me one today. Find me a textbook that says that published in the last ten years. I'm tired of seeing this trotted out as a straw man of the crowd who thinks sometimes comments are good.

Re: I hate comments

#32

Post by shrub »

kondro wrote: post #22
sankyo wrote: post #5

The comments that he shows are pretty worthless. However, comments are often necessary to explain WHY we are doing something. oven.setTemp(350) // 400 will burn them, 300 they will be mushy fluxCapacitor.setOption(THRESHOLD, 1.21E9) // lower thresholds will prevent return from time travel. Please see http://en.wikipedia.org/wiki/DeLorean_time_machine to review the physics

Both these are fixed by method extraction though. function setTemperatureToCookPerfectly() { oven.setTemp(350); } function ensureReturnFromTimeTravelPossible() { fluxCapacitor.setOption(THRESHOLD, 1.21E9) } Now wherever you see these lines in your code, you know exactly what they are for. To quote one of the Ruby Rogues, "A comment is a lie waiting to happen."

Until you change what those functions do, and then the function name lies.

Re: I hate comments

#33

Post by katbyte »

TimothyFitz wrote: post #11
eliben wrote: post #9

I don't mean to sound patronizing, but if you're implementing counters or banging out numbingly-boilerplate business logic for websites, comments are indeed useless. But when you're reading an obtuse 50-line function that implements some weird algorithm acting on some weird data structure, full of magic-like assumptions, you'd wish no one had deleted comments from it, or... had written them in the first place.

Actually, that's EXACTLY the case I had in mind. Obviously I couldn't put a 50 line function with weird data structures in my blog post, or it would be unreadable. But the point is that comments for that function are bad! They'll rot if you ever change the function or the assumptions at all. Instead, you should break the 50-line function up into smaller functions, and add assertions and test cases for all of those "m…

I've worked on code like that, and i'm sorry but i would rather read a 50 (or even couple 100 if appropriate) line function implementing specific functionality that is well written and documented with comments then have that critical information split up into a multiple functions and test cases spread out over multiple files. Sometimes functionality belongs together and it would be far more difficult to get that all that disjointed information into coherent mental model.

Not to mention how test cases and function names would just not cut it for explaining things like why the current implantation was chosen over more obvious, simpler ones, why the magic like assumptions are necessary and documenting the bugs/quirks in the underlying library or framework that are not obvious. Things like why call object.SetValue() instead of property object.value = x? Or Free memory from this call here, but not here, because the framework takes care of it.

I prefer commented code, even if it is over commented, because at the very least it is a way for the last programmer to explain why she implemented things the way she did.

Re: I hate comments

#34

Post by talmand »

kondro wrote: post #22
sankyo wrote: post #5

The comments that he shows are pretty worthless. However, comments are often necessary to explain WHY we are doing something. oven.setTemp(350) // 400 will burn them, 300 they will be mushy fluxCapacitor.setOption(THRESHOLD, 1.21E9) // lower thresholds will prevent return from time travel. Please see http://en.wikipedia.org/wiki/DeLorean_time_machine to review the physics

Both these are fixed by method extraction though. function setTemperatureToCookPerfectly() { oven.setTemp(350); } function ensureReturnFromTimeTravelPossible() { fluxCapacitor.setOption(THRESHOLD, 1.21E9) } Now wherever you see these lines in your code, you know exactly what they are for. To quote one of the Ruby Rogues, "A comment is a lie waiting to happen."

Wouldn't that function name have to be more like setTemperatureTo350ToCookPerfectly400WillBurn300WillMush to match what the comment is saying?

What if later it is determined that the proper temperature should instead be 375 because at 350 they aren't quite cooked enough?

Re: I hate comments

#35

Post by eps »

Ah, to be young and wild, and have most of my limbs again...

Try expressing a relatively complex state machine with asserts. Then come back in a month and try converting all those asserts back into few English sentences.

Re: I hate comments

#36

Post by jamesmcn »

and also vi > emacs

But seriously. Comments are useful. Don't over use them, don't under use them. If you are being dogmatic about your comments, you are probably doing it wrong. Autodoc comments can be nice, when done properly.

Re: I hate comments

#37

Post by katbyte »

kjackson2012 wrote: post #8

What a terrible and self-righteous post. How is a test case supposed to explain why MAX_COUNTER is set to 5 or 20? Comments are the single-most important thing when writing code, in my opinion. When feature specs are lost, and documentation goes out of the date, you only have code. And if you're supposed to jump through hoops like test case code to try to divine WHY things are as they are, then you're dealing with re…

> I strongly suggest all developers to ignore this blog post, and to comment as best as you can.

Bad or to many comments are better then no comments. Its not exactly hard to remove them, their absence will never break the build unlike not understanding the implementation!

Re: I hate comments

#38

Post by barrkel »

TimothyFitz wrote: post #11
eliben wrote: post #9

I don't mean to sound patronizing, but if you're implementing counters or banging out numbingly-boilerplate business logic for websites, comments are indeed useless. But when you're reading an obtuse 50-line function that implements some weird algorithm acting on some weird data structure, full of magic-like assumptions, you'd wish no one had deleted comments from it, or... had written them in the first place.

Actually, that's EXACTLY the case I had in mind. Obviously I couldn't put a 50 line function with weird data structures in my blog post, or it would be unreadable. But the point is that comments for that function are bad! They'll rot if you ever change the function or the assumptions at all. Instead, you should break the 50-line function up into smaller functions, and add assertions and test cases for all of those "m…

OK. But the algorithm is over a 1000 lines split up into perhaps 50 20-line functions, and it's mysterious how the whole works by looking at the parts.

I have one particular piece of code, that I wrote, in mind. It was to implement anonymous methods in the Delphi compiler. Given an AST for a method from the parser, it had to rewrite the tree to turn captured local variable references into field accesses on a heap-allocated stack frame, turn anonymous methods into methods on this heap-allocated stack frame, and all while minimizing the number of passes over the tree. And this has to work recursively, which adds a surprising number of wrinkles about the ordering in which you can do things.

So for example any given pass may be building up accounting data needed by later passes. This is somewhat mysterious, because it seems like busywork; and why is it doing this here? Why not fold one pass into another? Why not move work between passes? Well, the subtle ordering problems are not clear at all when you're looking at things at the function level. You can only understand the pieces when you already understand the whole.

And this is why there is a very long comment block describing how this stuff works. Because figuring it out by reading the code is too expensive.

(That ~1000 lines of code took perhaps 4 months to write; having to integrate with rest of a large complex codebase adds countless more wrinkles.)

Re: I hate comments

#39

Post by katbyte »

kondro wrote: post #24
B-Con wrote: post #17

I personally have four reasons for writing comments. If a comment does not fall squarely into one of them, I try to omit it: 1) Why the code is doing what it's doing. What's the motivation? Why is a check necessary? What's the context? 2) High-level overview. 20 lines of code may speak for themselves, but a quick sentence can easily summarize it. I love well-summarized code. "Do X with the Y unless it's Z" is a reall…

3 & 4 are really the only two valid reasons to use comments, in my opinion. 1 & 2 are both better solved with method abstraction. Comments describing what code is doing is always a code-smell to me. If you have 20 lines of code that is non-obvious, think about extracting it to one or more well-named methods.

his 1st point was not about commenting what code does but why it is done the way it is. I don't see how you can extract all the required information (including web links or rational) explain the rational behind a implementation into a function name.

    // unroll loop for 50% speed increase. Optimal offset 4
    // 3: 25%
    // 4: 50%
    // 5: 40%  
    for(i=0;i
How could you extract that into a function name?

2 is definitely more an opinion, but I use XML comments on every function, object, parameter, return value with a quick summery because it integrates into my IDE and is used to generate API and library documentation that is invaluable to developers who don't necessary have the code, only the documentation.

Re: I hate comments

#40

Post by katbyte »

Without comments how do you produce documentation for your code?

I put XML comments on every function, object, property etc giving them at the very least a short summary. These are then compiled into documentation xml that integrates with the IDE providing pop-up documentation for objects and functions without needing to see the source code. This xml is then compiled into actual html documentation is also used for APIs and libraries that other developers use without any access to the code.

Maybe documentation falls outside of the purview of source code comments... but i don't think so and i find it really handy to have the source code self documented with comments keeping docs and code in the same place.

Post reply on HN