DEV Community

loading...
Cover image for Code Smell 05 - Comment Abusers

Code Smell 05 - Comment Abusers

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

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

Problems

  • Maintainability
  • Obsolete Documentation

Solutions

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

Examples:

  • Libraries

  • Class Comments

  • Method Comments

Sample Code:

Wrong

Right

Detection:

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

Relations:

More info:

Tags:

  • Comments

  • Declarative

Credits

Photo by Volodymyr Hryshchenko on Unsplash


This article is part of the CodeSmell Series.

Discussion (5)

pic
Editor guide
Collapse
1e4_ profile image
Ian

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

Collapse
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

Collapse
1e4_ profile image
Ian

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