<p dir="ltr">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.<br>

Comments explaining every step of the process will crowd the codebase.<br>
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 ...</p>
<div class="gmail_quote">On Apr 2, 2014 9:10 PM, "Gonzalo Odiard" <<a href="mailto:godiard@sugarlabs.org">godiard@sugarlabs.org</a>> wrote:<br type="attribution"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><br>
<snip><br>
<div>> True, not much documentation in the code.<br>
> We don't use comments in every function or method,<br>
> and the code should be easy to read,<br>
<br>
</div>May be I'm wrong but with comments and descriptions, I think, it<br>
becomes easy to understand the working for newbies.<br>
<br>
Assuming that the person reading the code knows nothing about what<br>
it's supposed to do. Comments then can explain every step of the way.<br>
Sorry to say but I think well commented functions will make the code<br>
easy to read. Correct me if I am wrong.<br>
<div><br>
but honestly<br>
</div></blockquote><div><br></div><div><br></div><div>The code should be easy to understand, to know what is doing.</div><div>Usually comments are more useful to explain "why" is doing</div><div>what is doing, when is not obvious. </div>

<div>Develop need a lot of love to make it easier to understand.</div><div><br></div><div>Of course, newbie is a relative category :)</div><div>You will understand more and more with time and dedication.</div><div><br></div>

<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div><br>
If you are stuck with this task,<br>
> maybe can look at other easier bugs<br>
><br>
> <a href="http://wiki.sugarlabs.org/go/Activities/Develop#Pending_tasks" target="_blank">http://wiki.sugarlabs.org/go/Activities/Develop#Pending_tasks</a><br>
<br>
</div>Thanks for the useful link. But now that I have shared my problem and<br>
have spent a couple of days with it. I think, I should not let go that<br>
efforts in vain before getting the output. Otherwise it can make me<br>
feel depressed ;)<br>
<br>
And it's a problem with understanding only. Everything is there, I'm<br>
trying again with some other approach :)<br>
<br>
Thanks for being there and for that precious reply :)<br>
<div><div><br>
<br></div></div></blockquote><div><br></div><div>Is ok, keep the communication alive.</div></div><div><br></div>-- <br><div dir="ltr">Gonzalo Odiard<br><br><div>SugarLabs - Learning Software for children<br></div></div>
</div></div>
<br>_______________________________________________<br>
Sugar-devel mailing list<br>
<a href="mailto:Sugar-devel@lists.sugarlabs.org">Sugar-devel@lists.sugarlabs.org</a><br>
<a href="http://lists.sugarlabs.org/listinfo/sugar-devel" target="_blank">http://lists.sugarlabs.org/listinfo/sugar-devel</a><br>
<br></blockquote></div>