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

[Michael Homer]

On Sat, Apr 12, 2008 at 2:08 AM, Daniele Maccari <gobo.users at gmail.com> wrote:
> 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?
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.
> > - 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.
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).
> > - 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"?
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.
> > - 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?
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.

> Mmm, that's one thing I wondered about: imo, reading "#dash found" on
> the same line as else, could be interpreted as a comment about what the
> else block does, while this is not the case, iirc. Normally such lines
> should go just after a block's closing bracket, but not having it here,
> I thought placing it after the if would have been more comprehensible,
> to some extent.
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