On Sat, Sep 18, 2010 at 00:31, Tim McNamara <[email protected]> wrote: > > There are other forces at play. I recall one thread on the development list > that said there should not be in-code documentation in order to maintain the > quality of the contributions of prospective developers. The reasoning was > that if individuals are not able to understand the code by reading the > source, then they are not qualified to contribute to Sugar's core.
Are you sure of that? I think we want to make Sugar's code as easy as possible to understand, even to people who won't end up contributing code. Though of course you have to balance other considerations, I think the choose of Python makes such conflicts pretty rare. What may have been said is that if my code needs inline comments to make easier to understand what is happening, it may be because I need to try harder so the code's _intentions_ are clearer. API docs, adding intermediate variables, finding better names for variables and functions, splitting the code in new functions, classes or modules are ways to make the code intention more explicit without duplicating this information in inline docs. Sometimes for performance reasons or other extraordinary circumstances the code is more obfuscated than we would like it to be and then an inline comment explaining what is going on may be helpful, but with Python I feel it's rarely the case. Regards, Tomeu _______________________________________________ IAEP -- It's An Education Project (not a laptop project!) [email protected] http://lists.sugarlabs.org/listinfo/iaep
