[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

RE: master e4896fc 1/2: Add a new 'flex' completion style

From: Drew Adams
Subject: RE: master e4896fc 1/2: Add a new 'flex' completion style
Date: Thu, 14 Feb 2019 15:22:12 +0000 (UTC)

> what is better: writing a subpar docstring for an
> internal function, or keeping it undocumented.

That depends on what makes it subpar.

A subpar doc string can be so just because it is slightly
incomplete or slightly incorrect or misleading.  In this
case it might well be better than no doc string.

But a subpar doc string can also be so because it gives
a very wrong idea of what the object is/does.  In this
case it might be worse than no doc string.

This should be obvious.  The devil is in the details.

In general, we should have doc strings - including for
"internal" functions (IMHO).  But the doc strings should
be accurate and helpful, not inaccurate or harmful.

(Not saying anything about the doc strings mentioned
in this thread.  Just responding to your wish for a
too-general rule/judgment as to which is better: bad
or none.)

reply via email to

[Prev in Thread] Current Thread [Next in Thread]