On 2/9/07, Gary Wilson <[EMAIL PROTECTED]> wrote:
>
> ohloh thinks so too [1]:
> "Across all Python projects on Ohloh, 13% of all source code lines are
> comments. For Django, this figure is only 6%.
... and yet, for all the lack of documentation, I discovered Django in
late November 2005, and by January 2006 I knew enough about the
internals to have contributed patches that convinced Adrian to give me
commit access (and I wasn't working on Django 24x7 during that
period).
Metrics are great and all, but they aren't the end of the story.
Metrics like documentation ratios are a great example of measuring
something because its measurable, not because its insightful or
useful. Writing code that is readable in the first place is much more
important. For any value of n, n lines of unit tests (which will
usually get measured as code) is much more useful than n lines of:
# set the current line number to 3
line_number = 3
But this kind of stupidity is exactly what documentation metrics reward.
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.
Yours,
Russ Magee %-)
--~--~---------~--~----~------------~-------~--~----~
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
-~----------~----~----~----~------~----~------~--~---
