re: Good comments explain WHY, not WHAT, and 3 more rules on writing good comments VIEW POST

TOP OF THREAD FULL DISCUSSION
re: I highly recommend taking a look at Clean Code by Robert C. Martin (a.k.a. Uncle Bob). The author argues there's no such thing as good comments as...
 

I'm all for having the minimum amount of comments necessary.

Also, there are lots of good reasons to have comments. Sometimes, you're at the boundaries of systems. Made-up example: you have to pass an empty object instead of a null or the other way around for whatever reason the other system (that you might not control) expects. You leave a comment. It's not about making a comment "I'm returning a null", it's about "I'm returning a null because the other library is behaving badly with an empty object or whatever."

Sometimes, you think a code might be easily refactored, but you plunge in it and several dependent classes later you realize there are justified reasons why the code is written a certain way. A small comment can save hours to the next scout who wants to "leave the campground cleaner."

Or, you're choosing a particular hashing algorithm for certain useful or important properties for your use case. Please leave a comment explaining why. If not, someone else might just modify it for a more popular algorithm without realizing the unexpected impact in performance and of security.

Especially in shops or projects with high turn-over or which lives for decades, history and business logic gets lost.

code of conduct - report abuse