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

11–20 of 55 posts

Re: I hate comments

#11

Post by TimothyFitz »

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 "magic-lik assumptions." Then get in the habit of reading tests first. Now your code-as-comments will never rot.

Re: I hate comments

#12

Post by TimothyFitz »

randomdrake wrote: post #3

Hopefully no one even moderately unfamiliar with the language the code is written in needs to find out how to fix something that is broken. Citing breaking code by using some global that makes the comment no longer true? Sounds like an abuse of globals or someone not cleaning up the comments, not the comments themselves. So many times I have had to repair code in languages I wasn't quite familiar in or that was simpl…

"This method takes a foo object, applies HTML encoding, and returns an array of the original and the clean code." could be a 3-line unit test that's just as clear to read, but has the side effect of actually being true instead of maybe being true!

I would consider that comment just as bad as the ones in my examples, but maybe not quite as obviously so.

Re: I hate comments

#13

Post by theevocater »

Comments are for why, code is for how.

Why is the counter =0? Comments explain why your assertions are reality. Not every assertion is going to be as obvious as "balances have to be positive". If I had a dollar for every opaque assertion I blew up or ran into in code that had no explanation as to why something had to not be 0 or >1mil or null or whatever I would be a rich man.

Re: I hate comments

#14

Post by randomdrake »

TimothyFitz wrote: post #12
randomdrake wrote: post #3

Hopefully no one even moderately unfamiliar with the language the code is written in needs to find out how to fix something that is broken. Citing breaking code by using some global that makes the comment no longer true? Sounds like an abuse of globals or someone not cleaning up the comments, not the comments themselves. So many times I have had to repair code in languages I wasn't quite familiar in or that was simpl…

"This method takes a foo object, applies HTML encoding, and returns an array of the original and the clean code." could be a 3-line unit test that's just as clear to read, but has the side effect of actually being true instead of maybe being true! I would consider that comment just as bad as the ones in my examples, but maybe not quite as obviously so.

Of course a better comment could be written. I was using a short and concise comment to illustrate how you can gain a huge amount of understanding in a single line versus parsing a long function definition. Other comments here make suggestions for writing good comments.

Re: I hate comments

#15

Post by makmanalp »

TimothyFitz wrote: post #12
randomdrake wrote: post #3

Hopefully no one even moderately unfamiliar with the language the code is written in needs to find out how to fix something that is broken. Citing breaking code by using some global that makes the comment no longer true? Sounds like an abuse of globals or someone not cleaning up the comments, not the comments themselves. So many times I have had to repair code in languages I wasn't quite familiar in or that was simpl…

"This method takes a foo object, applies HTML encoding, and returns an array of the original and the clean code." could be a 3-line unit test that's just as clear to read, but has the side effect of actually being true instead of maybe being true! I would consider that comment just as bad as the ones in my examples, but maybe not quite as obviously so.

The main benefit of comments that you seem to be missing is that they are in the right context. Unit tests, while useful and required, make for boring reading and are not right where you need them. If I need to open up a separate file and scroll through tons of other tests to find the unit test "docs" on a function, you've lost me already.

Re: I hate comments

#16

Post by saidajigumi »

I'll agree that good comments don't reiterate what is plain from the code. Truly clear, self-explanatory code is a joy to read. But the process of coding usually boils away any notion of why, leaving only the brain-compiled machine that implements the how. It's the original use-case, high-level policies, implicit contracts and so on that comments should generally focus on. Especially, as the author notes, since TDD infrastructure and culture has gotten so much better at covering the "how" in recent years.

Also, sometimes the code is sufficiently brain-compiled that it's utterly inscrutable. Early in my career I wrote a fast interrupt driver for the company's main product that had become quite heavily optimized, and practically every line depended on nuances of the related hardware's functionality. This code was written in two-column code/comment form, and had more lines of comments than lines of code. This was necessary for it to be at all maintainable. In theory, a later refactoring might have simplified this state of affairs... but that opportunity never happened.

Re: I hate comments

#17

Post by B-Con »

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 really fast read. (Function names obviously provide this sort of explanation, but sometimes a name is not obviously not always sufficient.)

3) Stubs / future notes. Sometimes you need to leave something stubbed out. If you have thoughts on what they code will need to be, leave a note about it. This is easily removed later.

4) Quirks. If the code does something that is not obvious, note that. Non-obvious side-effects, bugs, etc. Don't discover something painful, then leave the next person (possibly a future you) to re-learn that same painful lesson.

Code does stuff. Comments describe the code. Comments should not re-describe what the code does, they should be about the code and the code's context itself.

Re: I hate comments

#18

Post by alexchamberlain »

randomdrake wrote: post #3

Hopefully no one even moderately unfamiliar with the language the code is written in needs to find out how to fix something that is broken. Citing breaking code by using some global that makes the comment no longer true? Sounds like an abuse of globals or someone not cleaning up the comments, not the comments themselves. So many times I have had to repair code in languages I wasn't quite familiar in or that was simpl…

Is that really quicker than reading return array(foo, foo->encodeHTML())?

Re: I hate comments

#19

Post by grn »

randomdrake wrote: post #3

Hopefully no one even moderately unfamiliar with the language the code is written in needs to find out how to fix something that is broken. Citing breaking code by using some global that makes the comment no longer true? Sounds like an abuse of globals or someone not cleaning up the comments, not the comments themselves. So many times I have had to repair code in languages I wasn't quite familiar in or that was simpl…

Comments are useful when they provide information that is not in the code (e.g. rationale for the choice of an algorithm, source of a regular expression that parses an URL). Your example HTML encoding function can be coded as:

    def clean(foo)
        return [foo, foo.apply_html_encoding]
    end
The encoding logic should be contained in apply_html_encoding. The point is that most of the functions/methods that are 65 lines long are badly coded.
Post reply on HN