On Feb 8, 5:28 pm, "Russell Keith-Magee" <[EMAIL PROTECTED]> wrote: > # set the current line number to 3 > line_number = 3 > > But this kind of stupidity is exactly what documentation metrics reward.
I 100% agree that comments such as these are worthless. > Thats not to say that documentation isn't useful, or that certain > parts of Django's code don't require additional inline comments - just > that doubling the inline comment count in existing code won't > magically improve anything. If anyone has any specific suggestions, or > wants to contribute inline documentation to a specific module, feel > free to contribute. I agree that comment percentage isn't the whole story; however, there have been quite a few times that, as reading Django's code, I have asked myself why something was done a certain way. I have even asked the developers list about a couple things, and nobody could remember the exact reason. Only answers like "that's what the developers chose." Python is usually readable enough to grasp what a section of code is doing; it's the why? question that comments should be answering. If the above example were something like this: # set the current line number to 3 because the first two lines are always garbage. line_number = 3 Now, that's actually useful. I think Django developers would benefit from more comments like these. Gary --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Django developers" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/django-developers?hl=en -~----------~----~----~----~------~----~------~--~---
