R. Clayton (rclayton@clayton.cs.monmouth.edu)
Wed, 17 Jan 2001 19:01:09 -0500 (EST)
A colleage of yours recently sent me a message asking for help with a simple
program that opened a file and copied its contents to std-out. The problem was
This code runs correctly on a Windows platform but I cannot get it to
cooperate on Unix.
The first thing to note about this claim is that it doesn't contain enough
information. Monmouth runs at least four variants of unix (solaris, ultrix,
irix, and linux) and there are at least four variants of windows (95, 98, 2000,
and me). The first thing I said to myself when reading this claim is "which
unix?" (I might of said the same thing about windows, but since I don't know
anything about windows, the answer would be meaningless to me).
In this case, your colleague included a transcript showing the program not
working, and from that I could guess the transcript was from a cslab machine,
and that "unix" means "solaris." However, if you're going to ask your
colleagues to help you with the difficult task of fixing code, it is in your
best interest to make sure your colleague has an easy as time as possible
learning about the problem. If you needlessly complicate the easy parts,
you'll find that your colleagues, over time, become more and more reluctant to
help.
There's another reason to present detailed information. A difficult error in
code is an indication that the programmer has lost control of the code: the
code is doing something contrary to the programmer's expectations, and the
programmer doesn't know where or why or how. This can be a psychology damaging
place for a programmer to be, because outside observers may use the existence
of such errors as the basis for judging (fairly or not) the programmer's basic
competence. And when those outside observers are colleagues, the potential for
psychological damage is acute.
The natural human reaction to such a predicament is to avoid it; that is, to
not ask for help. But, that reaction is counterproductive (because the code
remains broken), futile (because if the code's has any importance at all,
somebody's eventually going to notice it's not working), and self-fulfilling
(because the quickest way to earn other programmers' enmity is to force them
to clean up after messes not of their own doing).
Fortunately, there's another reaction which has none of these disadvantages:
make sure there's enough information in a request for help so that potential
collaborators can quickly understand the nature of the problem. Not only does
this make it easier for them to agree to help, but it also implicitly says to
them "Hey, I know what I'm doing - I just have this little problem I can't
quite figure out."
It's also important to avoid going too far in the other direction by including
too much information, although, generally speaking, too much is better than too
little. The first question most potential collaborators are going to ask
themselves is "Is this person absolutely without clue, or is there some hope?"
You should provide enough relevant information to indicate hope; if there's
more information needed, your collaborator will ask you for it.
A good test for checking requests for help is the shoe-is-on-the-other-foot
test: before asking your colleagues for help, imagine someone came to you and
asked for help in the same way. What would you do? How would you handle it?
If you wouldn't agree to help someone asking you with your own request, you
probably need to fix it.
For example, if someone comes up to you and says
"My program crashed."
you're probably going to sympathetically murmur "How awful for you." and hurry
away with the excuse of being late for a meeting. However if the person says
"When I compile this program (show program) using borland c++ v5.2 on windows
95 and run it, I get this correct output (show output), but when I compile
the same program using g++ ver 2.29 under solaris 2.8, I get this incorrect
output (show output). Also, I get the same error when I use CC."
You're probably going to think "Hummm, in addition to providing useful
information - the program works here but not there; this is why it doesn't work
there; not only didn't it work there, but it didn't work there two different
times - this person is clueful enough be know the names of the tools and to
figure out the version numbers. Not only that, but this person is apparently
eager enough to find the problem that they'll use two different compilers to
check. O.k., I'll help."
Here's another example, taken from a help message I recently posted to a
mailing list
I was under the impression I'd managed to successfully install rep-gtk 0.15,
but when I ran examples/hello.jl, I got the following:
cl uname -a
SunOS clayton 5.7 Generic_106541-11 sun4u sparc SUNW,Ultra-5_10
cl examples/hello.jl
error--> (error "ld.so.1: rep: fatal: relocation error: file
/home/rclayton/local/libexec/rep/sparc-sun-solaris2.7/gui/gtk/types.so:
symbol rep_file_type: referenced symbol not found")
cl
Any suggestions as to what might be wrong?
Notice the things this message suggests about me:
I know enough to include version numbers when asking for help.
I know enough to install the software, and recognize when the install does or
doesn't go well.
I know enough about the software to realize that there are test cases, and I
know enough about the software to know how to run them.
I know enough about unix to use the uname command to provide extra
information.
All of these are suppositions, but they all suggest a general aura of
competence on my part (whether it's deserved or not is another question).
This archive was generated by hypermail 2.0b3 on Thu May 17 2001 - 12:00:05 EDT