re: The Importance of Quality Comments VIEW POST

VIEW PARENT COMMENT VIEW FULL DISCUSSION
 

If your code "requires" a lot of comments, it's bad. If your code is bad, it should not make it past a pull request.

I'd MUCH rather have clean, well-written code without distracting comments than bad code full of comments.

I'm a consultant, and the project I'm currently on is chock full of really convoluted, unclear, hacky code. It's also littered with comments. Comments that are often times outright wrong, rarely written coherently/legibly, and rarely provide value. Many of them are on the line AFTER the line they describe, too.

Rather than demanding that your team fills their sub-optimal code with comments, why not mentor and educate them on writing better code in the first place? I've written a blog post called "Comments Are a Code Smell" that covers a lot of my feelings/thought on comments in code: programming-is-easy.com/comments-a...

 

In my experience, even well-written code can be improved by comments and I'm pretty sure that if the code is well-written the comments will be where they should be and provide the information they should provide. And you are absolutely right, a bad comment can be a nightmare.

I spent a lot of time trying to figure out why we were using a custom library to find out that I was looking at the wrong library.

Of course, that teaching people to write better is a lot better, but that's something for another post.

Your personal experience with bad comments is exactly why I use comments only as a last resort. Once I write a comment I try to think of how I can express my intent in code with out the comment and look at ways to remove them through refactoring. With modern refactoring tools it is pretty easy to extract a method and name it with the comment you just wrote. So why not encourage that instead of writing comments that can easily go out sync or move and mislead people and waste time because the comment was wrong?

code of conduct - report abuse