nkadel at gmail.com
Fri Nov 27 12:34:50 AEDT 2015
On Thu, Nov 26, 2015 at 11:45 AM, Peter Stuge <peter at stuge.se> wrote:
> Nico Kadel-Garcia wrote:
>> > Does that really need a comment?
>> That is _precisely_ why it needs a comment. It's a selection of a
>> particular technology for a particular reason that someone may not
>> understand as important
> Not even if they understand what the command does? (Use another shell.)
> I dislike redundant comments, which this seems to be. As code change
> and comments don't, those comments end up creating a lot more confusion
> than they resolve.
> Having clear code is far more important.
> It's reasonable to require that someone reading code already knows the
> tools being used.
I'm familiar with the old "the code is the comments" approach to
documentation. The difficulty with it is exactly what we see here.
It's not clear, even to a reasonably intelligent bash progammer, that
the use of "exec" is to insure compatibility with fish and tcsh users.
I've used both, and in fact published the first public ports of tcsh
for SunOS, and even I'd have think carefully to deduce, from raw
principles, why my scripting in bash is written in a fairly ugly to
ensure compatibility with alternative shells. 5 years from now, I'd
probably have forgotten completely about this thread and be
hard-pressed to remember why I or someone else didn't simply quote
ordinary bash syntax there.
> It's not reasonable for code to educate readers on tools being used.
I suggest that it's very reasonable to explain particular choices in
code, especially when those choices were made for compatibility
reasons less common configurations. Failure to document such choices
leads to regression errors when someone unweaves the undocumented
Been there, done that, especially had screwups with underdocumented
and subtly incompatible or inconsistent tools for editing
More information about the openssh-unix-dev