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

41–50 of 55 posts

Re: I hate comments

#41

Post by moocow01 »

This doesn't address the practical real-world problem...

Most developers are under at least moderate pressure to deliver and usually their priority is this...

1) Make thing appear to work

2) Make thing actually work

3) Clean up code to pass a code review or not be yelled at by a coworker

4) Comment where things are necessary

In many cases we barely get past step 1 and a half and usually its not even our fault - the business case has been mostly satisfied and according to the mucky mucks its best to move onto the next feature. Yes most of us dream of places where we can craft our code to oblivion but its probably not the average reality unfortunately.

I think its great when somebody takes the time to comment - commenting is not fun and has very little upfront reward but can be a lifesaver when traversing complex logic. If you have the ability to leave a profuse amount of comments I can hide them when I dont need them and use them when I have no idea whats going on - comment as much as you like.

Re: I hate comments

#42

Post by potatolicious »

commanda wrote: post #10

I helped the author edit this post for clarity, but it took all I had not to argue with him because I strongly disagree with his thesis. My main language (Objective-C) is relatively less readable (compared to his main language of Python), and I would absolutely not be able to function in a team, or even with code I'd written myself over a week ago, without heavy commenting. I do believe he's right though with respect…

Not to mention code is imperfect. My main platform is Obj-C/iOS and there are numerous API bugs, workarounds, and bits of ugliness involved when integrating with third-party APIs and libraries. These definitely involve comments because they are incantations that have a reason for existing, where the reason is entirely non-obvious on examination.

God help the guy who rips out a seemingly innocuous line of code only to subtly break things underneath. Even a simple:

    // Hack around time parsing bug in iOS3+, see [StackOverflow thread]
saves hours of lost productivity.

We can get rid of comments the moment we invent a perfectly expressive language, where every single line of code in your entire stack is under your control and everything works exactly as advertised out of the box.

Until then, I'll keep commenting where I need to, and never when I don't.

Re: I hate comments

#43

Post by kondro »

katbyte wrote: post #39
kondro wrote: post #24

Earlier quoted context omitted.

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

I agree, performance optimisations like this definitely require significant documentation.

However, for what most of us do, these optimisations should be rare. More emphasis should be placed on code maintainability than performance of individual components in most situations. Hardware is cheap, developer time is expensive.

Re: I hate comments

#44

Post by kondro »

talmand wrote: post #34
kondro wrote: post #22

Earlier quoted context omitted.

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?

And what would happen in the original?

People have a tendency to believe what the comment says, even when the code says something completely different.

It's easy to say that you would update both the comment and the value at the same time. But I've seen mismatched comments in code all the time for even a contrived example like this. And then what do you believe? Is the comment right with an incorrect implementation, or is the implementation right with an incorrect comment?

Re: I hate comments

#45

Post by Xion »

alexchamberlain wrote: post #20

I've recently read Clean Code by Robert Martin and now totally agree with the OP; everyone should go and read it, though it's full of annoying Java, it does apply equally to proper languages.

The reason you call Java annoying is exactly the one why Java code is so conducive to refactoring practices described in Clean Code: it mandates great verbosity.

Everything in Java is Big Deal, even something like a simple loop going through a collection and applying a one-liner to every element. In Java, you have to divide things aggressively for code to remain readable and maintainable. Otherwise it's way to easy to lose the big picture.

When methods are few lines tops, their names are descriptive, and you have explicit types of arguments and return values, it's no wonder you hardly ever need to comment anything.

Other languages can be very different in this regard. Take Python, ironically the language author's using in his examples.

Python is terse and expressive; does not specify types in code; has everything as first-order values; prefers short names due_to_naming_convention; and makes extracting code into functions a significantly bigger deal (everything is public, needs to have docstring, etc.). Those traits often need to be offset by a little more prose than you would put into code in other languages.

So while Clean Code certainly sounds convincing (I know I treated it almost like a revelation), it needs a little more perspective. Commenting practices are just one more tool that you need to match to the job - and language - at hand.

Re: I hate comments

#46

Post by Ives »

katbyte wrote: post #37
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!

That's not exactly true, if the comments and the code have at some point diverged, the comments can only serve to confuse the reader.

Re: I hate comments

#47

Post by fotbr »

kevinpet wrote: post #31
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.

I just know what I and my classmates went through. The commenting requirement wasn't from any book, it was a requirement coming from the professors who taught the courses.

Re: I hate comments

#49

Post by alexchamberlain »

Xion wrote: post #45
alexchamberlain wrote: post #20

I've recently read Clean Code by Robert Martin and now totally agree with the OP; everyone should go and read it, though it's full of annoying Java, it does apply equally to proper languages.

The reason you call Java annoying is exactly the one why Java code is so conducive to refactoring practices described in Clean Code: it mandates great verbosity. Everything in Java is Big Deal, even something like a simple loop going through a collection and applying a one-liner to every element. In Java, you have to divide things aggressively for code to remain readable and maintainable. Otherwise it's way to easy t…

Erm no... I'm a C++ developer. I call Java annoying because it is inefficient and has a garbage collector.

Re: I hate comments

#50

Post by Xion »

alexchamberlain wrote: post #49
Xion wrote: post #45

Earlier quoted context omitted.

The reason you call Java annoying is exactly the one why Java code is so conducive to refactoring practices described in Clean Code: it mandates great verbosity. Everything in Java is Big Deal, even something like a simple loop going through a collection and applying a one-liner to every element. In Java, you have to divide things aggressively for code to remain readable and maintainable. Otherwise it's way to easy t…

Erm no... I'm a C++ developer. I call Java annoying because it is inefficient and has a garbage collector.

And how these particular flaws of Java are relevant to the comments-or-not discussion at hand?
Post reply on HN