Docstrings considered too complicated

[Robert Kern]

On 2010-03-01 11:22 , Andreas Waldenburger wrote:

> Back in the software world: Those guys write code that works. It does
> what it's supposed to do. Why should we care where they put their
> comments?

Software usually needs to be maintained and extended over the course of its 
lifetime. The original team that wrote it may not be available in the future.

Furthermore, docstrings are not comments. They become part of the function 
object and can be introspected at runtime. This is a very important tool when 
working with code at the interactive prompt and for the collection of API 
documentation. Comments are less useful than docstrings; the OP's complaint was 
that his programmers were putting the function documentation in other places 
than docstrings, rendering them less useful than they could have been.

-- 
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless enigma
  that is made terrible by our own mad attempt to interpret it as though it had
  an underlying truth."
   -- Umberto Eco