Topic
Current CGL states that every method and class 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, packages, classes and properties without comment if it does not provide additional value
Pro
- Less “noise”
- Higher percentage of comments you should actually read
###Con
- Less strict rules, developers and reviewers need to think about comment necessity (and content) more
Additional Info
- PSR does explicitly not state anything related to comments
Proposed CGL text
[inspired by the coding machines best practices]
If you cannot use a type-hint, then a docblock documenting types is necessary. Please add PHPDoc to your code if it provides additional information. For example detail the content of arrays using the Object notation, if the return type is mixed and cannot be strictly annotated, add a @return tag. If parameters or return types have specific syntactical requirements, document them.
Vote:
- Yes, I support the proposal.
- No, I disagree with the proposal.
- I don’t care either way.