> > * Document the why, not the how > Does the 'why' implicate documentation for an abstract description of the implementation design (if not obvious) and the (reference to) underlying algorithms?
I just looked at the sage review checklist and did not find and advice to check for appropriate developer documentation (e.g. class design or reference to implemented algorithm) If that is missing it may and will cost for a new developer/maintainer unreasonably big effort to understand a design or reconstruct an algorithm from the source, what is often mandatory to maintain or extend existing implementation. Jakob Am Montag, 5. Januar 2015 11:36:23 UTC+1 schrieb Volker Braun: > > The __init__ docstring is used as the class docstring if there is no > separate class docstring, this is what I would recommend if you want it > seen. Alternatively you can force sphinx to show it with a .. automethod: > instruction. > > As for what is appropriate to document, the usual adages apply: > > * Document the why, not the how > * Place the documentation as close to the relevant code as possible. > > Anything that affects only a single method has no place outside of that > method. If it can be written as a code comment, then that is preferrable. > Only very high-level documentation should ever be placed in the class > scope, e.g. "Performance-critical: This class implements geobuckets for > non-communative polynomials". > > > -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at http://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
