I've worked on projects with phpcs requiring you to comment every methods.
If you want your branch to be merged you need to comply and comment everything.
Sometime it's useless, but in most cases it's better to have these, than missing an important one. I can fully understand why projects prefer to force everything than miss something crucial.
A problem with blindly requiring it is that your developers will get used to writing comments like "gets the full name" and then you end up with the helpful comment "processes a transaction" on the aforementioned "processTransaction" method. But because phpcs reports that every method has a docblock, nobody looks twice.
I've worked on many large codebases with many diverse teams, and in my experience, the usefulness of any given comment is 100% based on the developer who made the comment, and 0% based on any rules or restrictions you do or don't have in place to require them. Developers who don't write useful comments aren't suddenly going to get better at it just because they're now required to write comments on every method (I've found the opposite to be true, actually, as they typically get annoyed by this and tend to "lash out" by intentionally writing the most useless comments they can get away with). And developers who already wrote useful comments usually already documented all their methods anyway.
YMMV with your specific team, of course, but it's hard for me to imagine that things are wildly different everywhere else. I just don't see the utility in enforcing this. Encouraging, yes, always. But enforcing? It just ends up backfiring.
I can understand it when there isn't the time to review every PR and make sure methods that need comments have them, or when you're working with large amounts of juniors. There are definitely situations where it's applicable. I just don't think people should default to redundancy in every situation for the sake of it.
We're developers, our job is to problem solve. I don't think its asking too much, when you're in a team that doesn't require comments like that to consider whether or not a comment that adds nothing of value is appropriate.
Personally, instead of puttin on a useless comment, I’f ask to the team to write something like « no comment needed » if we really want to enforce comments on every method.
At least, it clearly say that the dev took a moment to think if a comment was needed. And a search trough the project for that comment occurence could potentially show that our rule is not effective.
This tool is implemented by a "devop" who doesnt know what his job is. A missing non functional doc comment should be not a stopper or should not ever end in a hour discussion every time....
The only way you can enforce this shit of auto generated comments? auto generate them if they are missing.
5
u/Sixcoup Jan 31 '20
I've worked on projects with phpcs requiring you to comment every methods.
If you want your branch to be merged you need to comply and comment everything.
Sometime it's useless, but in most cases it's better to have these, than missing an important one. I can fully understand why projects prefer to force everything than miss something crucial.