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

[Michael Homer]

On Fri, Apr 11, 2008 at 8:51 PM, Daniele Maccari <gobo.users at gmail.com> wrote:
> Mmm, well, I'm doing to change anything anybody will find erroneous/not
> clear, so keep suggestion coming.
It's funny you should say that. After some discussions on IRC:
- Some of the (inline) comments are a bit unnecessary ("Print out
notes for this script, if any.", "Quiet suppresses output"). I think
they're remnants of when you were commenting for your own
understanding, so they could be removed.
- For if/then, the comment should be either on the same line as the
then, or on the subsequent lines, not in between the if and then
(there are two of these)
- Jonas doesn't like you correcting his grammar. I think you should do
it anyway, because I like consistency.
- Some of the functions need more discussion of their side effects:
Show_Version terminates the script, for example, which should really
get a mention somewhere.
- The general principle was that the code should stand on its own
except when it's unclear, or it's necessary to explain why it's doing
what it is. "Read every line of the example and print it indented." is
good, because the following line isn't terribly clear without a lot of
thought, but "Print out examples" above it is obvious from `if [
"$scriptExample" ] ;then echo "Examples: ", so it isn't really
necessary.
- The blank "#<space>" lines in function comments (which are otherwise
great) take up a bit much room. You can only fit so many lines on a
screen, so blank ones lose you some real estate.
- It was also resolved to general agreement that I should say these
things *before* I commit patches. I suppose that was a valid point,
all things considered.

Another patch to those issues would be great, and (everybody) keeping
those in mind while commenting in the future. Also making sure you're
working from the latest SVN when you generate the patches.
-Michael