Is it consider bad practice to formally document implementation code?

Question

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?

Answer 1

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.

Answer 2

1. Public methods are used within a larger scope than non-public ones, and by a broader range of persons.

2. Non-public methods change more often than public ones (when the application is mature enough).

When it comes to comments, my first assertion means that it is much more important to document public methods. Those are the methods which would often be accessed by persons who don't necessarily have time (or interest) in exploring all the internals of the code: they just need to use the method, and they need to know how to use it. Inversely, those who will be interested by non-public methods are the persons who are often familiar with the class, and if not, they will have to become familiar with it, since they are modifying the class (otherwise, they wouldn't have to access non-public methods in the first place) or even the concerned method itself.

The second assertion means that it is costlier to keep the documentation of non-public methods up to date, especially when considering the ratio between public and non-public methods. If the method changes too often, it means that the documentation is read by fewer persons compared to the documentation of a public interface which remains the same for months or years.

To conclude, small-scope, non-public methods usually don't need as much documentation as public interfaces, and they are much more volatile. In other words, there is less money saved (in terms of future developers' time) by documenting a non-public method than a public one, and more money wasted constantly updating the documentation.

This explains PEP-8 guideline. One can imagine, obviously, some examples where it is absolutely crucial to document a non-public method, and examples where a public method is so self-explanatory, that it needs no comments. Those are the cases where that PEP-8 guideline should not be followed.

Answer 3

Documenting implementation code is not only not a bad practice, it is recommended and even necessary if the codebase is large. However, there is another style of documentation required and it serves another purpose than the documentation of the public code.

The public code must be documented such that users know what to do. Each piece of documentation should be as self-explanatory as possible such that the user doesn't have to read pieces of documentation for one hour before he can use a function. It must be clear, complete, easy to understand, even if this might make it more verbose.

On the other hand, internal documentation is meant to be read by people who are interested in maintaining the code base. Thus, it can assume a greater level of familiarity with the project and it should be more concise.

Personally, I feel like docstrings are too verbose for implementation code. I aim for self documenting code (i.e. expressive enough names, variables) and, if required, I add some comments.

Of course, docstrings for private code don't hurt per se, but keep in mind that they are longer and they require much more maintenance than a simple comment, without adding much value.

Answer 4

The very some paragraph you cited explains that you should use comments to document your non-public modules, function, classes and methods. Docstrings are documentation for users of your code, comments are documentation for mantainers of your code.