docstrings vs language comments

[Sridhar R]

When writing a python library, we can use docstrings for methods and
functions that are part of API. But what about comments for non-API
objects or python application code?

For applications, docstrings are not really much useful. Instead
language comments are prefered for them.

Language comments (starting with #) are usually considered to be a
little more readable than docstrings (when reading the source code for
understanding it).

So for non-API objects language comments will be prefered.

Thoughts?

 

[Terry Reedy]

When writing a python library, we can use docstrings for methods and
functions that are part of API. But what about comments for non-API
objects or python application code?

To my mind, docstrings are for saying how to use a module/class/function
(what is does and i/o specs) while comments are for saying how it does it
(the algorithm, which could change without changing the interface).

For applications, docstrings are not really much useful. Instead
language comments are prefered for them.

Docstrings and comments are for the benefit of programmers who use and
revise the code, not for non-programmers ultimate users. I don't see much
difference in this respect between a library function and a specific
application function.

Language comments (starting with #) are usually considered to be a
little more readable than docstrings (when reading the source code for
understanding it).

I think I personally prefer and find it easier to read docstring material
(as defined above) if it is consistently in docstring format.

So for non-API objects language comments will be prefered.

Thoughts?

You are entitled to your different opinions, but stating them as facts does
not change their status as opinions ;-).

Terry J. Reedy

 

[Rick L. Ratzel]

There was a thread similar to this almost two weeks ago. While the
advantages of using docstrings is obvious, I remember commenting about
some of the typically minor disadvantages of docstrings which seem
consistent with your belief that hash-sign comments might be better
suited for stand-alone applications:

---
The only perceived disadvantages that I'm aware of occur when you don't
use the -OO flag. Docstrings end up in frozen executables and .pyc
files, visible through the use of the "strings" command (which is a
problem for people who think the information is hidden from the binary
file like a comment). The binary files are also ever so slightly larger
when docstrings are used instead of comments. However, using -OO
removes docstrings in addition to applying optimizations...the frozen
executable or resulting .pyo files have no docstrings and are a bit smaller.