Results: Voting: CGL: Allow methods without docComment


(Susi Moog) #1

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


(Susi Moog) #4

This topic was automatically closed after 7 days. New replies are no longer allowed.