> > I don't understand what you mean by "design". If you code isn't readable > then that can't be fixed by documentation, only by writing clear code. >
The program architecture, the grand picture (if not obvious): class diagrams, state transition diagrams, internal code interdependencies/implemented design patterns, call graphs; everything a developer cannot extract by a code inspection without major effort in comparison to reading the developer documentation. AFAIK, Nathann Cohen did hit this issue when working on the poset implementation. Adding a link/reference to the underlying algorithm is definitely desirable. > Despite from the fact that (I guess) this basic rule is obvious, in reality its often violated, at least in Singular code. For me that is a reason to extend the review checklist by this point. What do you think? Of course we cannot put everything on the checklist. In case it turns out mandatory to put on the checklist that the people should breath, I probably would give up and move away ;-) Am Montag, 5. Januar 2015 16:00:54 UTC+1 schrieb Volker Braun: > > On Monday, January 5, 2015 3:15:07 PM UTC+1, Jakob Kroeker wrote: >> >> Does the 'why' implicate documentation for an abstract description of the >>> implementation design >> >> > I don't understand what you mean by "design". If you code isn't readable > then that can't be fixed by documentation, only by writing clear code. > > >> (reference to) underlying algorithms? >>> >> > Adding a link/reference to the underlying algorithm is definitely > desirable. > > -- 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.
