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

“My Code is Self-Documenting”

ericholscher.com

Post reply on HN
Print view View original

31–40 of 100 posts

Re: “My Code is Self-Documenting”

#31

Post by gnaritas »

codr4life wrote: post #2

I find that the commonly touted opinion that comments should only reflect why, and avoid all duplication; is misguided. The only places where I will elaborate on why is where I can see obvious room for improvement but I'm still waiting for the bigger picture to stabilize, or I'm adding a dependency that I'm not really happy with. Otherwise my comments mostly express the intent of the code in regular prose and have to…

If your comments just say what the code does, they're redundant and unnecessary. Good comments explain things the code can't, like why you chose a particular algo, or why some piece of code needs to exist. Most code when written well requires no comments. Comments like yours, that repeat what the code does, I simply delete.

Re: “My Code is Self-Documenting”

#32

Post by nercury »

kyberias wrote: post #20

I think the Uncle Bob quote is good: "Code comments are not the Schindler's List. They're not pure good." If a line of code has a comment attached to it, the reader needs to understand both the code and the comment. The comment is written in natural language. There are multiple ways of understanding it. It must be written with great care so that people reading it don't misunderstand it. Otherwise it will likely just…

No, the reader must not need to read the function to understand how it works.

The idea would be that the function names are so good that one does not need to read the function contents, right?

But some things are complicated and may not be expressible with the function name alone.

That's why people write comments. To help readers understand the code.

Let's say I am implementing some algorithm. I may mention the performance characteristics in the comment. Or I may let the readers dig into the code to find out what they are. Seriously, please don't follow "no comments" rule dogmatically.

Re: “My Code is Self-Documenting”

#33

Post by Johnny555 »

BigJeffeRonaldo wrote: post #22
joekrill wrote: post #10

Earlier quoted context omitted.

Well this seems like a problem with code reviews (or lack of), rather than with the comments themselves.

It's a matter of incentives. Business folks don't care about comments unless they have a dev background. Your options are then to focus on the incentives present in the situation, or materially harm your own life and well-being by working extra hours to make up for your management's inability to manage.

In my company, the business folks have no idea what the code looks like or whether or not there are comments.

All they care about is that the code works, and that features can be delivered on time.

That second part "delivered on time" includes maintaining the comments along with the code since it makes the code more readable, and eases future changes. If Management doesn't give you time to write maintainable code (which includes keeping comments in sync with the code), then you may as well start looking for a new job because the technical debt is going to pile up and it's going to get harder and harder to meet deadlines.

Re: “My Code is Self-Documenting”

#34

Post by kyberias »

From my experience there is a correlation between the amount of code comments and defects in the code. The more I see comments in the code base of a module, the more likely it doesn't have any (unit) tests and the more it has defects.

Yet this may just indicate that the code is complex and therefore required comments and contains bugs.

In any case, high comment density is a code smell.

Re: “My Code is Self-Documenting”

#35

Post by Isamu »

Most of our very large and complex code base lack comments.

But just yesterday I came across a particularly good comment in an else block, that summarized the story of "how could we have gotten here", and it involved far-flung failures and not so obvious interactions. Very informative to have that right there.

Re: “My Code is Self-Documenting”

#37

Post by ntsb »

derefr wrote: post #17
js8 wrote: post #12

Earlier quoted context omitted.

As others have said.. Code doesn't depend on variable/function names either. Yet you don't argue they fall out of sync, you simply update them. And this should be done for comments, too.

Code does depend on variable/function names. When you change the name at the definition, your code fails to compile until you also change the name at each usage. This is not true of comments. If we could make outdated comments produce compilation errors, we would live in a wonderful world :)

> If we could make outdated comments produce compilation errors

I really hate it when the compiler ignores my comments.

Re: “My Code is Self-Documenting”

#38

Post by kyberias »

nercury wrote: post #32
kyberias wrote: post #20

I think the Uncle Bob quote is good: "Code comments are not the Schindler's List. They're not pure good." If a line of code has a comment attached to it, the reader needs to understand both the code and the comment. The comment is written in natural language. There are multiple ways of understanding it. It must be written with great care so that people reading it don't misunderstand it. Otherwise it will likely just…

No, the reader must not need to read the function to understand how it works. The idea would be that the function names are so good that one does not need to read the function contents, right? But some things are complicated and may not be expressible with the function name alone. That's why people write comments. To help readers understand the code. Let's say I am implementing some algorithm. I may mention the perfo…

No.

If I have a function and I need to understand _how_it works_, that is, how does it implement some algorithm, of course I have to read every single line of code to understand how it works!

If the function is named "quicksort", for example, and I suspect it has a bug, I really have to read it to understand whether it implements the quicksort algorithm correctly.

Re: “My Code is Self-Documenting”

#39

Post by sqeaky »

derefr wrote: post #17
js8 wrote: post #12

Earlier quoted context omitted.

As others have said.. Code doesn't depend on variable/function names either. Yet you don't argue they fall out of sync, you simply update them. And this should be done for comments, too.

Code does depend on variable/function names. When you change the name at the definition, your code fails to compile until you also change the name at each usage. This is not true of comments. If we could make outdated comments produce compilation errors, we would live in a wonderful world :)

But it could. With C++ at least you can get your build to break on some comment errors. If you enable Clang's pedantic warnings, or if you setup Doxygen to emit warnings in the same format as your compiler and incorporate Doxygen execution directly into your build, you can get errors and warnings on bad comments.

Doxygen supports documenting function parameters, C++ template parameters, return values then Doxygen and Clang can tell if the name listed for some of those things doesn't match the actual code or if a certain kinds of comments are missing. This won't tell you the documentation is wrong, but it would stop you from adding or removing a function parameters while ignoring documentation comments entirely.

If you want to go crazy you can write Clang plugins using LibTooling and run and code you want and analyze the comments any way you choose.

Re: “My Code is Self-Documenting”

#40

Post by quicklyfrozen »

wellpast wrote: post #3

> Code comments document the why, not the how. I disagree. The _what_ is what your comments should tell me. The contract, and its preconditions and postconditions. Nothing more, nothing less.

So where would you document the "why" then? This is often the question I find most difficult to answer when reviewing code (including my own) -- after all, I can ferret out the what from the code.
Post reply on HN