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

[Daniele Maccari]

Michael Homer wrote:
> On Sat, Apr 12, 2008 at 2:08 AM, Daniele Maccari <gobo.users at gmail.com> wrote:
>   
> What would they do exactly? A high-level overview of what the whole of
> some large block does if it's non-obvious would be fine, but the
> comments on what some particular function does (Quiet, say) should go
> in its documentation rather than where it's used.
>   
Mainly that, as you said. However, looking again at the code, I removed 
some of them, since indeed they're quite redundant.
> Just before the if would be fine too, if the comment pertains to the
> whole if/elif/else block. In between the terms is a little ugly
> though. If the comment is short enough, put it on the same line as the
> then (but consistency with the other elifs/elses in the section should
> probably override that).
>   
Yes, I used the "after then" rule, to be consistent with the rest of the 
script.
> Anything that has an effect beyond returning a value (by output or by
> return). Changing variable definitions, outputting to the user (also
> what Show_Version does), terminating the script are all side effects.
>   
So, for example, Add_Option updates the options arrays: has it to be 
considered a side effect?
I'd say yes, since arrays are global to the whole script.
> That was what I meant. I think Jonas is referring to blank lines
> around comments where there's an indentation change, which aren't
> really necessary either.
>   
Ah, ok. Actually, I've chosen to wide the all-# line enclosing 
functions' headers to 80 chars, could it be ok? This way we'd save 
precious space while maintaining some sort of compatibility for standard 
terminal size. I also removed the blank lines you and Jonas pointed at, 
when possible.
As a side note, I could have inserted some blank lines between chunks of 
code when I felt them a bit "compressed", this making them not so 
clear/readable. Please let me know what you think about this.
> The "# dash found" doesn't go with that block. I think it would be
> clearer just to remove it entirely, the comment after the else is
> clearer about what's happening. Maybe "fi # Short/long option"?
> -Michael
>   
Yes I'd thought about something similar like "single dash/double dash", 
to make it clear what ends and what starts.

Last but not least, I've got a little doubt about what this piece of 
code does, could you please help me? http://pastebin.com/m78380740

If I got it right, it loops through the current string's characters to 
find a valid shortening. At the end, if none was found, it "Log_Error"s 
the failure. What I cannot understand is why looping for all characters, 
shouldn't an option be identified by its first character only? Though 
maybe I'm missing the eval option=\${${i}} part.

Bye