DEV Community

Cover image for Code Smell 05 - Comment Abusers

Code Smell 05 - Comment Abusers

mcsee profile image Maxi Contieri Originally published at Updated on ・1 min read

Code has lots of comments.
Comments are coupled to implementation and hardly maintained.


  • Maintainability
  • Obsolete Documentation


1) Refactor methods.

2) Rename methods to more declarative ones.

3) Break methods.

4) If a comment describe what a method does, name the method with this description.

5) Just comment important designs decisions


  • Libraries

  • Class Comments

  • Method Comments

Sample Code:




Linters can detect comments and check the ratio comments / lines of code against a predefined threshold.


More info:


  • Comments

  • Declarative


Photo by Volodymyr Hryshchenko on Unsplash

This article is part of the CodeSmell Series.

Discussion (5)

Editor guide
1e4_ profile image

Depends on if you generate documentation through annotations in which case comments are good and very much needed, not the single line ones but phpdoc.

If you give examples of code I'd try and adhere to general standards which include not starting a file with <? But <?php. For beginners it's pretty crucial to not let them assume it's good to start with short tags 👍

Other than that nice tip

mcsee profile image
Maxi Contieri Author

Thank you very much for your comments

I choose <? instead of <?php because language is accidental.
I don't want to be tied to a particular language, could have been Js, Java etc.
I don't want articles targeted to php community. That's why I don't suggest php doc.
I don't think documentation is useful if you are declarative enough

1e4_ profile image

Everything in this post points to PHP.

I heavily disagree with no documentation. Just because you know what's going on doesn't mean someone that comes to a project later on.

Thread Thread
mcsee profile image
Maxi Contieri Author

That's why you need to write declarative methods, classes and attributes.

Methods are alive. They are maintained . They run with the tests.

Nobody maintains documentation. And nobody reads them

Thread Thread
mcsee profile image
Maxi Contieri Author

That's why tests are for.

They are alive, they are maintained and they don't lie