docstrings vs language comments

[Terry Reedy]

"Sridhar R" <sridharinfinity at yahoo.com> wrote in message
news:930ba99a.0406201027.516ea515 at posting.google.com...
> 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