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.
---

-Rick Ratzel


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.
> 
> Thoughts?



More information about the Python-list mailing list