[IAEP] comments in the code (was Re: Child in charge of FOSS or Sugar)

[Tomeu Vizoso]

On Sat, Sep 18, 2010 at 00:31, Tim McNamara <paperless at timmcnamara.co.nz> 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