I agree that the official Python docs are well maintained and achieve a
tough goal - the right balance of just replaying basic interface facts
on one side, or being overly prosaic on the other side. Nope, they are
well balanced giving enough of both extremes to get you going, place
repo code lookup links, and examples where needed.
And Python properly fills the __doc__ attribute on almost every function
or class, which is a big relief in interactive testing sessions to
quickly grasp a rarely used detail not in your muscle memory.
With Django thats mostly not possible, inspecting __doc__ or using
help(XY) does often not reveal any useful information.
> So no, I'd be a strong -1 to any recommendation suggesting that
> docstrings be used to clutter up the code.
I dont see how informative docstrings can clutter code, they are
visually well separated from code bodies, and most editors ven allow to
fold them.
The bigger issue I see with docstrings is, that they sometimes end up
being written too machine firendly, e.g. full of restructuredText
formatting, which hinders human reading to some degree, esp. if you
never used those formats yourself before.
--
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-developers+unsubscr...@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/django-developers/050016b3-7cb8-4f23-b389-819aa1663f12%40netzkolchose.de.
