Non-friendly documentation

I agree. It is easy to measure quantity whereas it‘s impossible to measure quality (which is also very subjective). It also invites gaming the system for example by having docstrings for the sake of having docstrings:

"""
    Foo

The Foo struct.
"""
struct Foo end

An anecdote: I was recently following along with a Golang tutorial and the linter in VS Code was constantly complaining about missing docstrings for exports. As a result, I added nonsensical docstrings like the above. Then the linter complained that one of the types had a “stuttering name” at which point I was horribly annoyed and just stopped. Moral of the story: Shaming people into writing docs can have unintended side effects and feels like a bad idea.

2 Likes