On Wed, Oct 03, 2001 at 05:29:27PM -0400, Erik Troan wrote:
> On Wed, 3 Oct 2001, Harry Putnam wrote:
>
> > One thing that would help would be to heavily comment all init
> > scripts. Maybe this isn't done because they change frequently or
> > maybe it is just assumed that any one paging thru them will be able
> > to follow the code easily, which is absolutely wrong in my opinion.
> >
>
> It's not done because we're understaffed, and just haven't had time. We
> agree that it should be done, fwiw.
Erik, here I will come down on you with 23 years of experience as a
software engineer, much of that as a contractor. I comment
_everything_ I write, even throwaway code. In my experience, you don't
have time to _not_ comment. Profusely.
As a contractor, I could walk away from what I write and say to the
customer, "Oh, you want to know more about this? Well, that's $75 an
hour." I don't. I have a standing offer that any of my customers may
contact me with anything they don't understand about my documentation
at any time after I finish the project. Only once have I been
contacted, and that was a M$ Word password problem in accessing the
documentation I had written, not with the actual project.
The reason you don't have time to not comment profusely is that it
will come back to bite you. Like this discussion. As software
engineers writing source code to be tossed out for all to see, you
should be _embarrassed_ not to have good comments in and other
documentation for your code.
Recall the cute cartoon of a child on a toilet, with a wad of toilet
paper in his/her hand. The job isn't over until the paperwork is
done. But even that is misleading: you should comment first, then
write code. It means you get your concepts down as you go, and can
refer to them later. It also helps to clarify your thoughts before you
write code.
I also find that if I take the time to prepare a good design document,
1) I complete the project much faster than I otherwise would, and 2)
the design documention contains a lot of what is necessary for user
documention.
>
> > Admittedly I am a rank amateur script writer but I usually have 40
> > percent or more comments in scripts that I expect to come back to at
> > some future date. And still sometimes have trouble seeing what I was
> > trying to do.
I comment C code from 40 to as much as 80% by file size. And that's in
addition to the design documents I describe above, which may be 80% of
the file size I produce.
>
> I'm not going to pretend that our init scripts are readable but rank
> amatuer script writers. Many of them are complicated, but they should
> all be comprehensible.
Some of them are comprehensible to me. But then I've been at this for a
while. I wonder how much luck someone whose sole exposure to shell
scripting is Microsoft .bat files will have.
>
> >
> > if [ -f /etc/sysconfig/i18n -a -z "$NOLOCALE" ] ; then
> > . /etc/sysconfig/i18n
> > if [ "$LANG" = "ja_JP.eucJP" -a "`/sbin/consoletype`" != "pty" ]; then
> > unset LANG
> > else
> > export LANG
> > fi
> > fi
> >
> > # Read in our configuration
> > [...]
> >
> > Note there is no clue whatever as to what the `if' clauses are doing.
>
> This is all really basic shell scripting. "man test" would make good reading
> some time, fwiw.
Erik, that's as much of a cop-out as "Real programmers disassemble the
executable."
You are good at shell scripting. Perhaps Harry isn't. Some comments
will help him along.
You want to try reading some of the Forth code I wrote 20 years ago,
before I learned the above about commenting? No? Well, neither do
I. That's why I started to comment profusely.
--
-- C^2
The world's most effective anti-virus software: Linux.
Looking for fine software and/or web pages?
http://w3.trib.com/~ccurley
PGP signature
