I was recently in a project where they had a git hook to enforce that every method, class and module has a documentation comment.
So, even a method Db.init() had to have a comment “Initializes the DB.”.
As a result, the quality of those comments in general was awful. If you have to fill in 20 documentation comments, you’re not going to go into huge detail, even when in some places a description might actually make sense.
And then as a result of that, 95% of comments were not worth reading, which meant no one read them, which meant no one fixed them or complained about them being bad in code reviews.
It was basically just wasted time, that we had to fill those comments in.
I was recently in a project where they had a git hook to enforce that every method, class and module has a documentation comment.
So, even a method Db.init() had to have a comment “Initializes the DB.”.
As a result, the quality of those comments in general was awful. If you have to fill in 20 documentation comments, you’re not going to go into huge detail, even when in some places a description might actually make sense.
And then as a result of that, 95% of comments were not worth reading, which meant no one read them, which meant no one fixed them or complained about them being bad in code reviews.
It was basically just wasted time, that we had to fill those comments in.