docstrings vs language comments
Rick L. Ratzel
rick.ratzel at scd.magma-da.com
Mon Jun 21 19:17:29 CEST 2004
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.
If you use a hash-sign comment, you're guaranteed that it won't be in
the binaries, which is a big advantage to some if that comment contains
highly sensitive documentation.
Sridhar R wrote:
> 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.
More information about the Python-list