Hacker News Reader

Comment by oweiler | Hacker News Reader

No one has ever said that you shouldn't comment your code.

"Comment the how, not the why."

When you read software engineering books like Clean Code, they are generally heavily in favor of writing good comments.

When you read programming books, like "Learn Language XYZ" books, there are generally no comments whatsoever because there is no need. Which makes sense in the scope of such books, but I think it accidentally sets a precedent for eschewing comments in the minds of many.

But.

Out in the "real world?"

I'd say 90-95% of coders don't comment a damn thing. At least that has been my experience working in the industry since the 90s.

Some coders are in the obnoxious and toxic "code should be self-explanatory" camp, which is objectively dumb. Code can't explain intent, such as business rules or weird shit you're doing to work around weird shit in external libraries or APIs or hardware bugs.

A greater number of coders are of the mindset that inline comments are bad and that things should be explained in the commit message and/or pull request. This is more noble, but I think it is not nearly as practical as inline comments for a variety of reasons.

Many coders also believe that comments make code harder to read. I find this baffling and dumb. Get a bigger monitor or get an editor that lets you collapse/hide comments with a keystroke.

A great deal of people have. Uncle Bob and his substantial following, for example.

Many of his followers perhaps, but at least in the Clean Code book there is a long chapter on comments, where about half is dedicated to "Good Comments" that include many reasons for when and how to comment code. Yes, it has a section titled "Comments Do Not Make Up for Bad Code"... but he also writes about how there "are certainly times when code makes a poor vehicle for explanation" and that some comments are "necessary or beneficial" like "Informative Comments" or "Explanation of Intent" etc. That chapter is one of the few I remember as somewhat useful in the book (I am not much of a follower or fan... but I did enjoy his Clean Architecture book).

I have a tendency to comment code that isn’t optimal and will need to be refactored for performance at a later date.

Not sure how many times I’ve been looking into a new performance issue as we grow, and come across one of my own comments.

Sort of falls into the Good/Fast/Cheap trifecta. When you have to do the Fast/Cheap bit, note when you know it’s not optimal so you can identify it quickly when you or someone else comes back to it.

Unfortunately there is/was a very loud group that said exactly that. The opinion was that code should be self documenting.

I have heard many people say this.

That's backwards. The code is the how, the why is what comments can add.

I don’t think you shouldn’t comment your code, but in my experience, good code doesn’t need much, if any, comments.

This is because I define “good code” as simple code. If code gets to the point that it needs to be explained with comments, then there’s a good chance there is opportunity for simplification.

In other words, if I can’t read code and follow what it’s doing — or why it’s doing it — then I won’t ask them to add comments, but to instead refactor/simplify the code. (This is assuming the code can’t be made more readable with simple name changes, which a lot of times is all that is needed.)

Yes, there are times when the “why”, even with simple code, needs to be explained. Comments in this case are fine. But ideally this is the exception and not the norm.

There are numerous cases where code needs comments. People who think identifier names are all you need are frankly frustrating. It forces co-workers to do reverse engineering any time they want to understand the code.

The most obvious case are API docs which includes internal APIs (means: any public method, in my codebases). Comments are much faster to read and understand than the source code, can be quickly pulled up by using the right hotkey in your IDE, and can be browsed via generate API doc pages in a browser. I don't want to read your function to figure out what it does, I don't want to guess how I'm supposed to use it from the name. I want proper docs.

The second most obvious case is where the reason for a piece of code isn't obvious. Typically this means bug fixes or workarounds, but can also be performance optimizations. If something isn't explained by a comment then sooner or later it's going to get accidentally changed. Unit tests aren't a complete replacement because you don't necessarily know what tests are for what lines of code, and often it's hard to unit test an obscure bug fix anyway (e.g. workarounds for OS level problems).

Reply on news.ycombinator.com