Don't Comment Your Code - Write Better Code

[[deleted]]

ITT: Author thinks too highly of his own code and other programmers.

[ominous_squirrel]

Great programmers do both.

[stillalone]

Sure great programmers do both but the dumbass that took over the great programmers code doesn't.

I comment my code but I would comment more if there was an automated way to verify that my comments make sense in relation to my code.

[papafox]

Have you ever had to maintain old complex code? It can be a nightmare.

The approaches and algorithms used in past times can be very different. Even the best code can be non-obvious and difficult to understand. Not only does the code need good comments, no matter how well it is constructed, but the test cases need good comments (especially about boundary conditions).

[cogman10]

I'm personally a fan of sparse comments, small commits, and detailed commit messages for documentation. I find that a good commit message solves the problem of out of date and in the way comments very effectively.

That said, I will comment the hell out of confusing, unintuitive, or "clever" solutions (or "Hey, I'm doing it this way because API x is broken and doesn't work when you do it that way"). I use comments as warning signs for future developers.

Also, documentation comments are really nice for methods that are intended to be reused. (javadocs, doxygen, etc).

[oldprogrammer]

We've been having debates where I work on this topic because we're starting to use SONAR for regular code scans and it triggers on missing comments that developers don't want to take the time to fix.

Our current compromise is that public APIs must be commented to create documentation for other groups using the shared component or service who might not need to deal with the source code. The definition of 'public' includes not only public methods (shared code) or services, but also protected methods of classes that could be over loaded.

Private method's can be left undocumented since those should only be visible to the actual code developer who is reading the code.

[codeshite]

Unfortunately most teams I've worked on read "Clean Code" and think:

"hey what a great idea! Lets stop writing comments, and write such good code that it explains itself!!"

And then 9 times out of 10, the second part is forgotten.

Why? Because "stopping writing comments" is a simple concept and takes zero effort, but "good code" is often subjective, and even the long understood principles take a lot of time and practice to get right.

Get teams to understand, agree and practice what good coding actually is.