Feature request: Generate module docstrings from startproject and startapp actions

[Matthew Laney]

Hi,

Going through my code with pylint, I found that there is no way to filter by the type of missing docstring. I.e. missing-docstring catches functions, classes, methods, and modules. As a result, it gives a warning on for every default Django file. Accordingly, I would like to suggest that the current automatically generated comments of "Create your __ here" that are generated for each file created by manage.py startapp be replaced with docstrings that follow the PEP 257 convention. The second line of the specification: All modules should normally have docstrings, and all functions and classes exported by a module should also have docstrings.

Thanks,

Matt

[Aymeric Augustin]

Hello Matthew,

I understand the suggestion, however, I’m afraid it priorizes the needs of the wrong audience. Experienced developers or teams who care about docstrings and pylint can use a custom project template for this use case. Conversely, newcomers who are still learning Django would likely leave a docstring stub untouched. I lost count of the number of copies of https://github.com/django/django/blob/master/django/conf/app_template/tests.py-tpl I git-rm’d over the years...

There’s no denying docstrings are useful, but many projects — even large ones — are doing just fine without adding one to every single module. I don’t believe Django should be exceedingly prescriptive in this regard because I’m afraid we’d just encourage the perversion of JavaDoc / PHPDoc / epydoc / etc., that is, docstrings written because they’re mandatory and add zero value, like """This module defines the models for billing.”””. Well, it’s called `billing/models.py`, I knew that already.

If that requirement was found in PEP 8 or more widely followed by the community, I’d be more open to encoding it in the default project template. PEP 257 sounds a bit self-serving there...

-- 

Aymeric.

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to django-develop...@googlegroups.com.
To post to this group, send email to django-d...@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/29041c35-cc01-464c-9405-d84f1acbc62b%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.