On Wed, 03 Mar 2010 18:40:00 +1300, Gregory Ewing wrote: > Ben Finney wrote: > >> Just as customers should demand both that a building be built to do its >> job well, *and* that its architectural plans meet measurable, testable >> industry standards of quality for independent re-use at some >> indeterminate later date. > > A problem is that it's very hard to come up with *measurable* standards > of code quality. > > There's no equivalent in the software world of specifying a grade of > steel or type of sand. The things that really matter are all subjective.
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. Or one can simply use *reason*: what justification is there for putting comments in strings at the top of the function? The only one I can see is if you are writing for an embedded device, you may want to remove doc strings to save memory -- and even that is implementation dependent. What justification is there for putting docstrings in functions? Code becomes self-documenting, you can run Python tools that extract and run doctests, standard tools in the standard library work, other coders will immediately understand what you have done, and (unlike the behaviour of string-comments) the behaviour of docstrings is guaranteed by the language. Unless you are writing for an embedded devise, there is NO objective reason for putting comments in strings above the function, and MANY objective reasons for putting them into docstrings. Okay, this isn't quite the same as measuring the strength of concrete under compression, but it's not a subjective choice like "tea or coffee?". -- Steven -- http://mail.python.org/mailman/listinfo/python-list
