PEP-8 clearly states which parts of your code should have documentation:
Write docstrings for all public modules, functions, classes, and methods. Docstrings are not necessary for non-public methods, but you should have a comment that describes what the method does. This comment should appear after the def line.
(emphasis mine)
And while the above excerpt says that providing docstrings for non-public(a.k.a implementation) classes/functions/modules are not necessary, I fell like doing so makes the code easier to maintain in the future.
However, most python code-bases I see seem to adhere(more or less)to what PEP-8 says above; omitting docstrings for implementation classes/functions/modules. With that in mind, I'm wondering if I should avoid doing this in the future as well. It seems that if other python devs are not doing it, there are probably good reasons why.
Would it be bad practice to continue to give docstrings to implementation code, or is this solely a matter of ones preference?
Best Answer
It is not necessarily bad practice to write doc strings for implementation code.
One thing to watch out for is that if the doc strings end up in official documentation, then other people might start to depend on internal details that you may want to be able to change at will. If that is a real concern for you, then you could also write the documentation in regular comments, rather than in a doc string.
Writing good documentation is hard and to most programmers (myself included) less fun than writing code. If you then add a bit of over-confidence on how readable your code is, then it becomes really easy to say "this internal function I just wrote is so clear, the code can stand on itself without additional documentation." The real proof of that statement usually comes several months later, when maintenance needs to be done and the code turns out to be less self-documenting than you thought.
It is very good on you if you can avoid that trap most of the time.