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

[Daniele Maccari]

Michael Homer wrote:
> 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:
>   
Glad to see partecipation, thanks :D
> - 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.
>   
He, actually, at least for me, deciding which comments are really necessary
and which aren't can give some headaches sometime, since I might lack some
knowledge about particular shell constructs/functions, so "marking" it 
helps.
But indeed you're quite right, most of them are there for my convenience.

Nontheless, I think some "section comments" could be nice too, at least to
show the first-read reader what some chunk of code does, even without 
reading through it,
what do you think about this?
> - 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)
>   
Ah, sorry, I suppose them to be a mix between Jonas' "same line 
comments" and mine usual
"just before the if" ones.
> - Jonas doesn't like you correcting his grammar. I think you should do
> it anyway, because I like consistency.
>   
Well, sorry to hear that, but I know Jonas and I think we can find a 
simple solution here, no problem by my side about changing my way of 
writing to adapt it to already present comments.
> - 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.
>   
No problem here too, I posted this one as a preliminar version exactly 
for such things ;)
Also, the "Notes:" section in the function's header serves precisely 
this purpose, so using
it would solve the problem. As a rule of thumb, what should be 
considered as a"side effect"?
> - 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.
>   
See the above comments about sections, but indeed some of them could be 
removed anyway.
> - 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.
>   
Mmm, I'm not sure to have understood this one. Do you mean the empty 
line between
the line of # and "Name:" at the top and its sister at the bottom? Or 
every empty line?
I the description part, I used them mainly to distinguish the "one line" 
description, and the
more detailed explanation following.
> - 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.
>   
Hahaha, I agree on this point :D
> 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
I'll update the wiki guidelines accordingly to your (and Jonas, I can 
well suppose :) ) suggestions, thanks again for the help.

Bye