[Sugar-devel] Comments in code [ Gonzalo Odiard ]

[Sai Vineet]

I believe well written code *is*  documentation. Expressive verbose code,
with function named following conventions like _ for private methods, a cb
at the end of the function name to convey it's a callback, etc makes the
code a hundred times more readable and intuitive than normal code IMHO.
Comments explaining every step of the process will crowd the codebase.
I think we should adopt a policy of documenting functions in large hard to
comprehend codebases, but documenting small ten line functions just seems a
waste of time ...
On Apr 2, 2014 9:10 PM, "Gonzalo Odiard" <godiard at sugarlabs.org> wrote:

>
>> <snip>
>> > True, not much documentation in the code.
>> > We don't use comments in every function or method,
>> > and the code should be easy to read,
>>
>> May be I'm wrong but with comments and descriptions, I think, it
>> becomes easy to understand the working for newbies.
>>
>> Assuming that the person reading the code knows nothing about what
>> it's supposed to do. Comments then can explain every step of the way.
>> Sorry to say but I think well commented functions will make the code
>> easy to read. Correct me if I am wrong.
>>
>> but honestly
>>
>
>
> The code should be easy to understand, to know what is doing.
> Usually comments are more useful to explain "why" is doing
> what is doing, when is not obvious.
> Develop need a lot of love to make it easier to understand.
>
> Of course, newbie is a relative category :)
> You will understand more and more with time and dedication.
>
>
>> If you are stuck with this task,
>> > maybe can look at other easier bugs
>> >
>> > http://wiki.sugarlabs.org/go/Activities/Develop#Pending_tasks
>>
>> Thanks for the useful link. But now that I have shared my problem and
>> have spent a couple of days with it. I think, I should not let go that
>> efforts in vain before getting the output. Otherwise it can make me
>> feel depressed ;)
>>
>> And it's a problem with understanding only. Everything is there, I'm
>> trying again with some other approach :)
>>
>> Thanks for being there and for that precious reply :)
>>
>>
>>
> Is ok, keep the communication alive.
>
> --
> Gonzalo Odiard
>
> SugarLabs - Learning Software for children
>
> _______________________________________________
> Sugar-devel mailing list
> Sugar-devel at lists.sugarlabs.org
> http://lists.sugarlabs.org/listinfo/sugar-devel
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.sugarlabs.org/archive/sugar-devel/attachments/20140402/fb01946d/attachment.html>