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.
0 voters