[Python-Dev] About code comments policy (and Handler order in urllib2)

"Martin v. Löwis" martin at v.loewis.de
Mon Mar 5 19:16:12 CET 2007

Facundo Batista schrieb:
> The question is what to do when we found a question in a code. Reading
> urllib2 I found:
>   # XXX why does self.handlers need to be sorted?
> I found the answer, so I deleted that line, and added a comment in that
> place just to clarify. 
> Shall I do something else? 

You should check whether documentation needs to be clarified. In this 
case, I see a single mention of handler_order in the documentation, and
that only mentions that the attribute exists and can be set. Not having
looked at all at the functionality: Do you consider this documentation
sufficient? Would you think users may need to know about this feature?
If so, do you think they have what they need to use it just by reading
the documentation?

If you really feel zestful (is that proper usage of the word?), you 
could try to study who added the remark, and when, and who added the
documentation, and when. I often do that to verify that I really
understood the purpose of the question.


More information about the Python-Dev mailing list