When I'm writing code, I'm trying to solve a specific problem,
but when I write documentation, I'm trying to clearly convey what
is actually going through my head. The shift is sort of subtle but
it's awkward because I know what I'm thinking and what I'm trying
to do, but as I write documentation there's a constant uncertainty
of "will someone else be able to understand this, even if it's me
in a week?"
I certainly should start using docstrings, that's for sure. Writing
documentation in general is something I should put more resources into
because generally I only do it when I have already written some
pseudocode planning out my process and that sort of naturally flows
into becoming comments or docstrings. In reality, a lot of times
I'm trying to code as fast as I can think and so as things develop
quickly, I'm not taking the time to actually explain what's going on
and to go back later and add those kinds of docstrings feels awkward,
even though that exercise is still worthwhile in the grand scheme
of the design.
Pat Wick
pwick