> 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

Reply via email to