[gobolinux-users] Gobo wants you! (to comment its scripts)

[Hisham]

On Mon, Apr 7, 2008 at 5:43 AM, Daniele Maccari <gobo.users at gmail.com> wrote:
> Hello everybody,
>
>  me (macco) and Aitor (A_Tuin) started a little "project", which simply
>  consists in commenting every single scripts used by GoboLinux to carry
>  things out, thus making them a bit more comprehensible to normal people
>  (and devs) not that deep into gobo since the first day.

Awesome initiative!

>  So far, we're almost done with CheckDependencies and OptionParser. Aitor
>  will star to look at the Scripts/Functions dir, which indeed has a lot
>  of material to work on :D
>
>  No real guidelines exists, but as rules of thumb:
>
>  1- Don't comment every single line, just try to give an overwiew of what
>  some function does, specifying what a line does only if really
>  obscure/crucial.
>
>  2- We used the following format:
>
>  http://rafb.net/p/WdkyCe11.html (not definitive, it was a try of mine)

Some suggestions from a dev, inspired by looking at the linked file:

* IMO, the most helpful comments are the ones that explain the
arguments of a function and what do they return. When commenting
dynamically typed languages (such as Python or Lua) it's also useful
to comment what are the expected types for arguments and return
values.

* Too much comments can become a maintenance burden, and if the effort
of maintaining them rises, then they may become out of sync with the
code and end up doing more bad than good. The comment block at lines
285-323 is great, but trivial comments such as line 165 should be
avoided. On the other hand, comments like line 363 are great because
they explain the intention of the code (ie, "why" it does, instead of
"what" it does).

* Avoid comments like line 254: when something is not understood, just
leave it uncommented. This way someone else can notice more easily
that a particular part of the code was left unexplained.

Hope this helps!

-- Hisham