Ranter
Join devRant
Do all the things like
++ or -- rants, post your own rants, comment on others' rants and build your customized dev avatar
Sign Up
Pipeless API
From the creators of devRant, Pipeless lets you power real-time personalized recommendations and activity feeds using a simple API
Learn More
Comments
-
I hate docs for that reason. 99% of docs are like that. No matter if it’s Microsoft, Google or Apple or whatever.
This trend needs to stop. -
Inline documentation is there to document unobvious reasons, explain usage, and tell static analyzers about expected types. They are not there to repeat the code block's name and signature.
An exception might be an actual library meant for the public where the docstrings are the source for generating actual documentation and every public code block has to be fully documented with examples of use and detailed explanations of all known edge cases and how the code reacts to them. -
slar3001yDo you have any documented code guidelines?
We (try) to resolve unnecessary code review comments by documenting mandated style as well as things that are optional. So you can't comment if an optional thing missing just because it's your personal preference.
If comments show up that aren't covered by the guidelines, we discuss them, make a call if they are mandatory or optional and document the decision.
The people that religiously put "missing docstring" on code reviews... Like, I get why but... Who hurt you? Especially in typed languages, where there's a function called "can compute stuff" with a foo type, and I add a docstring that's "whether we can compute stuff for the given foo"...
rant