Wandering Thoughts archives

Docstrings versus comments in my code

One of the great not quite arguments in the Python world is between docstrings and comments, specifically which one you should use in your code. My answer is that I use both, although more comments than docstrings, but I use them for different things.

My comments are primarily written as internal documentation; how a function operates, why it operates that way, the high level logic and structure of the code, and so on. Docstrings, when I write them, are external documentation, covering things like how to use a module, a class, or a function.

Since I mostly write Python code for myself, my comments shade into a bit of external documentation; often I stick a little summary of the function into a comment instead of a docstring. Partly this is because I feel that comments are less formal than docstrings; as docstrings actually are external documentation, I feel the need to make them decent external documentation.

(And sometimes I hijack docstrings for entirely unrelated purposes, since they can be easily looked at from inside Python. DWiki's code uses docstrings to describe how to use text macros, for example, because it means that I can just embed usage descriptions into the actual macro functions instead of having to maintain separate help text somewhere else.)

What I see as the formality of docstrings also makes me nervous about writing them in the 'wrong' format, or at least a less than helpful and clear format. These days there does seem to be a relatively consistent docstring format for things, but I don't think it's very well described anywhere I could easily find (PEP 257 does not qualify).

(This entry is sort of inspired by reading this.)