Hacker News Reader

Comment by maayank | Hacker News Reader

"Explain code in private messages. Write wikis that nobody uses."

What the reasonable alternative though? What's the happy medium?

>>Explain code in private messages.

...and this is the natural result of the 'no comments allowed in the code' nazi's that seem to permeate lots of organizations. For the life of me I could never understand that particular bandwagon.

I for one love it when I go back into my code after a few years and a few well placed comments remind me why I did what I did last time I worked on it.

I took over leadership of a project where the previous CTO was a "code should be self documenting" proponent and enforced a comment limit with a precommit hook. I think I made some of the developers cry when I asked why there were so few comments.

even worse, I worked on a project where you were not allowed to have comments in code, but if you really felt a need to explain something, you could put it in the projects readme.md, referencing the file and line number and why you did what you did.

Talk about a bone-headed outcome of claiming 'we don't allow comments in our code' mentality.

OMG. I fell afoul of commenting AND coding "standards" when I used Duff's device in an embedded system and my comment was something like.

/* Using Duff's device see <reference> for speed and code size */

The poor developer assigned to replace it with "better code" had an impossible task because they couldn't find anything to replace it that wasn't either much slower or much bigger.

I would suggest you to read Clean Code by Robert C. Martin. There's a whole chapter about comments in the book.

I try to write informative comments. That said, 99% of the comments I see are

* Useless, like "locks the mutex" before a mutex.lock().

* Contrary to the code, like "This parameter contains the proc name without the instance" and then the parameter does contain the instance.

* Dubious, like it's not obvious what the comment means nor if what you are doing follows the comment or not.

Worst thing is when the code and the comment contradict and there's no good reason to trust one over the other in what the code should do (never go to sea with two chronometers).

I suppose it depends on the codebase you are working on. If it's your own code the likelihood of you agreeing with the comment increases, ofc.

When a coworker does not understand what a function call does, you add a verbose enough comment directly to the code.

Zero effort solution is to have permanent group chats so background info like discussions on requirements are searchable.

Reply on news.ycombinator.com