11
atheist
282d

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"...

Comments
  • 5
    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.
  • 4
    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.
  • 4
    Data types + well named code > docstrings
  • 3
    Do 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.
  • 1
    @slar we found mobbing essentially solved this
Add Comment