Current CGL states that every method has to have a docComment / phpDoc - even methods without parameters or return types - for example constructors, resulting in comments like “constructor”. I’d like to propose to make the description part of the docComment (and thus the whole comment if no params/return type) optional to also get rid of simple getter/setter comments (what’s the benefit of the “get the ID” comment on top of a getId() method?).
Impact
CGL Adjustment to allow methods without comment
Pro
Less “noise”
Higher percentage of comments you should actually read
Con
Less strict rules, developers need to think about comment necessity (and content) more
That php-doc-standard also just “recommends” using a DocBlock. That would allow us to interpret it as Susi suggests. I agree over-simple doc-blocks don’t help at all. Our PSR-standards also don’t forbid us to skip docblocks? (We wanted to stick to established standards, even if they might be unpopular).
Imho if we make it optional we will still be able to point out during code-reviews for which cases we definitely would want a docblock. We also currently check if the docblock makes sense or needs to be more precise/extensive/… So that should work out.
Hey,
I really appreciate the idea of leaving out unnecessary comments out. Right now, we often have the situation of comments for the sake of comments. They blow up the code and have no additional value.
However, I see the danger of lazy developers using that weaker rule as an excuse to stop commenting. But as Stefan says that could be caught at the code review.
Absolutely yes. It’s what we do (deliberately violating the TYPO3 CGL) in our projects already. Especially when you use the PHP7 style native type hinting for parameters and return types the phpDoc in many cases is completely useless.