> On Dec 3, 2014, at 18:46, exar...@twistedmatrix.com wrote:
>
> On 12:55 am, gl...@twistedmatrix.com wrote:
>>
>>> On Dec 2, 2014, at 20:05, exar...@twistedmatrix.com wrote:
>>
>>> Are there lots of useless docstrings on nested function definitions purely
>>> for the sake of twistedchecker? Or are there undocumented nested functions
>>> that are actually a little bit difficult to understand on their own?
>>
>> twistedchecker does not presently require nested function definitions to
>> have docstrings. I recently merged a fix to an incongruity where it was
>> requiring this of classes defined within functions:
>> <https://github.com/twisted/twistedchecker/commit/4af4e97f99d6e5f683b65272a8dbe7bce2087aa7>.
>> So this one, at least, we can cross off for the future :).
>
> The broader context of this suggestion was that we should inspect the
> codebase to see what policy changes would improve the quality of the
> code/documentation while reducing the effort required to develop and maintain
> it.
>
> It sounds like you have some ideas about such changes already. Does that
> mean you'd like to suggest them (presumably in the form of issues filed
> against twistedhecker) instead of doing this investigation?
In this one case, I believed I was simply bringing our tooling into line with
existing policy. twistedchecker already doesn't require docstrings on
callbacks, it seemed like a clear bug that it required docstrings on those
callbacks if they existed inside a class statement.
The letter of the policy is a little ambiguous, and perhaps it should be
updated.
<https://twistedmatrix.com/documents/current/core/development/policy/coding-standard.html#docstrings
<https://twistedmatrix.com/documents/current/core/development/policy/coding-standard.html#docstrings>>
says docstrings "should" always be used, but it doesn't say "must". And, as
written, it has no exception for callbacks, which clearly contravenes our
existing tooling and practice.
I do have a couple of other more specific ideas and I will almost certainly
file twistedchecker issues for them :).
More broadly speaking I think it would be great to have some investigation into
our code-quality issues. I think that there are definitely lots of useless
docstrings for the sake of twistedchecker, and I'm not quite sure how to
classify those.
-glyph
_______________________________________________
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python