Code has lots of comments.
Comments are coupled to implementation and hardly maintained.
TL:DR; Leave comments just for important design decisions. Don't explain the obvius.
Problems
Maintainability
Obsolete Documentation
Readability
Code and comments duplication.
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
<?
final class ChatBotConnectionHelper {
//ChatBotConnectionHelper is used to create connection strings to Bot Platform
//Use this class with getString() function to get connection string to platform
public $id; //ChatBot Id
function getId() { //Gets id value
}
function setId($id) { //Sets id value
}
function getString() {
//Get Connection String from Chatbot
//....
}
}
Right
<?
final class ChatBotConnectionSequenceGenerator {
private $name;
function connectionSequence() {
//....
}
}
Detection
Linters can detect comments and check the ratio of comments / lines of code against a predefined threshold.
Relations
More info
Tags
Comments
Declarative
Conclusion
Leave comments just for important design decisions. Don't comment a method with a bad name, rename it.
Credits
Photo by Volodymyr Hryshchenko on Unsplash
If you have to spend effort looking at a fragment of code and figuring out what it’s doing, then you should extract it into a function and name the function after the what.
Martin Fowler
This article is part of the CodeSmell Series.
Last update: 2021/06/06
Oldest comments (10)
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
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
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.
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
That's why tests are for.
They are alive, they are maintained and they don't lie
I can't see any difference between your "wrong" and "right" examples.
There's a bug in devto with embeded code and caches. I've updated the article and inlined code. Can you check it out ?
Yeah, it looks right now.
You are going way over the edge with most of the "code smells". Also, you seem to lack experience with other languages. I've seen few of your "code smells" and they seem to be either things that are easy to abuse, misconceptions, wrong tools in the wrong place, etc.
The "comment abuse" comes from stakeholders (and software) demanding stuff to be commented, even if its obvious. For example, the linter might require each function and field to be commented, so you can't just skip it. So you put obvious comments, like you shown in the post.
On the other hand, there are many places where LONG comments are acceptable. Language that promotes such approach is python - with documentation being generated from comments, and having "doctests" being tests directly embedded in the comments. This way, they come into the documentation, and are validated as regular unit test.
Your conclusion - is very opinionated and short sighted.
Someone forgot about PHPDoc in the "Right" section 🙄
Some comments may only be visible to logged-in visitors. Sign in to view all comments.