Docstrings considered too complicated

[Gregory Ewing]

Steven D'Aprano wrote:

> True, but one can look at "best practice", or even "standard practice". 
> For Python coders, using docstrings is standard practice if not best 
> practice. Using strings as comments is not.

In that particular case, yes, it would be possible to
objectively examine the code and determine whether docstrings
were being used as opposed to above-the-function comments.

However, that's only a very small part of what goes to make
good code. Much more important are questions like: Are the
comments meaningful and helpful? Is the code reasonably
self-explanatory outside of the comments? Is it well
modularised, and common functionality factored out where
appropriate? Are couplings between different parts
minimised? Does it make good use of library code instead
of re-inventing things? Is it free of obvious security
flaws?

You can't *measure* these things. You can't objectively
boil them down to a number and say things like "This code
is 78.3% good; the customer requires it to be at least
75% good, so it meets the requirements in that area."

That's the way in which I believe that software engineering
is fundamentally different from hardware engineering.

-- 
Greg