Post by f***@gmail.comsingle author Slackware had a unique/superior documentation method.
[snip]
...but I can't find any methods to capture-the-underlying-logic of my own
scripts, for later understanding/editing. It reminds me of the
undisciplined hacking of BASIC, before the days of *STRUCTURED*
programming. Where can I find documentation on this problem?
Well, I'm not a professional programmer, but I have programmed for many
years as a hobby and also as part of my profession. So I have a point
of view.
To write well documented, easy to use code you need to do these things:
1. You need to write good code. Bad code generally defies
understanding. Documentation doesn't help much.
2. This is my pet peeve: Use a coding style that includes logical
indentation and blank lines (white space). Code makes more sense when
it is easy to read, and logical, consistent use of indentation and
white space helps this immensely.
3. When you can (and that is perhaps *always*) word your code so the
logic of your if-blocks is clear. This is another peeve, especially in
Bash. There are lots of ways to write an if-block in Bash. Maybe I'm
just dumb, but I think you owe it to yourself and your users to write
them like this:
if [ "$blah" = "blah" ]; then
run something
fi
Or for compound statements
if [ \( "$blah" = "blah" \) -o \( "$fred" = "farley" \) ]; then
run something
fi
4. In bash use "\" to continue lines as needed. for example, the
above, might be better written:
if [ \( "$blah" = "blah" \) -o \
\( "$fred" = "farley" \) ]; then
run something
fi
5. Also for Bash learn how to use the "cat << DONE" method of
providing output, and use it to avoid indenting when there isn't room.
This a compromise, but that's how I do it. It works for me. For
example:
if [ \( "$blah" = "blah" \) -o \
\( "$fred" = "farley" \) ]; then
cat << DONE
Here is some output. It is very helpful to do it this way, because
your editor will make new lines for you where needed, and you don't run
of of room on the line because of the space needed for "echo..." or
"printf...".
DONE
fi
6. Don't just program, but be a student of programming. Study it.
Collect and read books about it. And especially, keep extensive notes
(or "lessons") organized by subject and/or by command which tell what
you have learned by testing and/or Internet searching.
Don't just learn something, document it in a way which allows you to
find it again by use of grep. Or better make a tool which invokes grep
for you. For example, I have a tool that lets me recursively search
for a string like this:
forall . grep Bob
Then use your tool when searching through your lessons for tips about
how to do something. The above would search for all occurences of
"Bob" in the current dir and all sub-dirs. Go to your lessons dir
first, then give the search command. My lessons dir has sub-dirs by
command and sometimes by subject, and occaisionally those sub-dirs are
further divided.
7. Put examples of code you have written in your lessons dir, but also
organize your collection of code, so that it can itself be a source of
documentation. Bash is great for this. Bash scripts and function
definitions, especially when clearly written and documented, both serve
a purpose and serve to document how to do something.
8. Write code which helps you write, document and organize your code.
You will write better code and document it better if it is easy to do
so. I use a system that I developed myself called SAM (available at
http://sourceforge.net/projects/sam-kernel). It is all Bash plus three
short C executables. It works by manipulating the environment. The
result is a command line prompt which reflects both the dir you are in
and the state of your PATH variable. It doesn't show all of PATH, just
what you have added to it. It uses the concept of menus where a menu
corresponds to a dir which is currently included in PATH. For example,
this bit of code adds a dir to the path, executes the printreport
command which is in that *menu*, then returns to the previous menu:
bound /mnt/joresorc/tools
printreport
bye
In the usual Bash fashion, you can enter the above lines at the command
line or you can type then into a script or function defintion and run
the script or function.
At any point in the use of SAM this command will display a menu
description telling you the available commands and the syntax for how
to use them, as well as any other notes you have added:
menu
SAM simply builds the output from the contents of a file called
$level/menu.dat where $level is the path to the dir which is the
current menu. For example
bound /mnt/joresorc/tools
menu
will change to the menu at /mnt/joresorc/tools (updating the prompt,
path and functions accordingly), then display output built from
/mnt/joresorc/tools/menu.dat
And to allow you to write SAM tools which operate on the current
environment without having to source them, SAM also adds and removes
functions (to and from the environment--I hinted at this in the
previous paragraph) as needed when changing menus. To add functions to
a menu, put defintions for the functions in the menu dir each having
this first line:
#OK SAM
This has been a cursory overview of what SAM does. SAM is essentially
just Bash, so of course it is sometimes a nuissance, but it has served
me well. Most certainly, writing and using SAM has shaped the way that
I write and use code--hopefully for the better. You are welcome to
download SAM from Sourceforge and use it and modify it per the license
agreement.
Or write your own code which helps you write, document and organize
your code.
-Joe