The Big Rig

My Web site now has a new page entitled “The Big Rig: Accessible computer workstation for an unassisted quadriplegic user”, wherein I describe the computer system I put together for my wife.

Questions, suggestions and comments can be submitted to this blog.

Copyright © 2009 Possum Technologies, All Rights Reserved.

The tyranny of poor tools (1)

I recently had the experience of checking in some changes to a source code file. I had changed just a few lines, but my editor (Emacs) had, as I had instructed it to do, automatically removed the trailing whitespace from each line whenever I executed the “save-buffer” command. Trailing spaces are worse than worthless, so removing them is a Good Thing, right?

Because the “diff” tool in common use where I worked was not configured to ignore differences consisting only of whitespace, each trailing space that Emacs had deleted was highlighted as a source code change demanding attention from the code reviewers. Instead of a few lines appearing as changed, there were dozens.

I found these spurious differences annoying, but thought the right thing for code reviewers to do was to ignore them, since these were not real changes.

Imagine my surprise when I was asked to put the deleted whitespace back!

The reason given was that, in addition to the burden on the code reviewer of having to ignore all these changes-that-are-not-really-changes, the source control software might have trouble handling those “differences”.

Now, the person who made the request is a smart fellow, no bozo. Yet he felt obliged to urge me to spend precious development time in order to better adapt to that broken source control software.

Of course, many organizations developing software have a filter that removes trailing whitespace as part of the check-in. But the relentless pressure to get things done, coupled with the fact that humans are more intelligent and more adaptable than either organizations or software, means that we humans do the adapting, even when the entire point of the organizational procedures or computer software is to help us do our jobs.

Copyright © 2009 Possum Technologies, All Rights Reserved.

Perverse genius

We might well consider a person who is nearly always right in his/her judgment a genius.
What about the person who is nearly always wrong?

If one were to make a series of binary decisions, where one alternative was right and the other was wrong, by flipping a coin, one should tend to be right about 50% of the time.  A person who is wrong in making binary decisions, say, 95% of the time could be valuable as an oracle, provided we always remember to reverse the profferred advice.

Such a person could help us in choosing investments, for example. One perverse genius advised me to buy Food Lion stock, just before ABC News broke the scandal about Food Lion's meat department. I have no reason to think this person had any inside knowledge, just a knack for wrongness.

I have known a few individuals with this sort of instinct for consistently choosing wrong technical approaches to problems. For example, given a file F1 consisting of a 2000-line procedure P that contained a line with the single statement S, instead of changing:

   S;

to

   if Some_New_Condition then
      S;
   else
      T;
   end if;

in procedure P in file F1, the perverse programming genius created a file F2 that was a perfect copy of F1, except that procedure P was renamed to Q and the call to S was replaced by a call to T, then visited the multiple sites whence P was called and replaced the call to P with:

   if Some_New_Condition then
      P;
   else
      Q;
   end if;


My first attempt to make sense of this approach led me to think that this person wanted to please management by increasing his number of lines of written source code, and thus his apparent productivity, but he revealed to me that his true aim was to not alter F1 in any way, thus avoiding breaking any of the code contained in it!

In this instance, the perverse genius was not presented with a single binary choice but with many possible designs. Still, if you were responsible for approving the perverse genius's code changes, you would have a binary choice: adding three lines of code to a single source file versus adding over 2000 lines of code, creating one additional source file and modifying every source file containing a call to P.

Copyright © 2008 Possum Technologies, All Rights Reserved.

Deeply nested statements

Problem: Deeply nested statements (usually “if” statements) tend toward unreadability.

Discussion: It is often best to rule out pathological cases before attempting to perform routine work. For example, one should ensure that a pointer is valid before attempting to dereference it, or that an array index is within the bounds of the array, or that one of many necessary functions has not returned a value indicating failure. Too many levels of nesting tend to obscure source code.

The structured programming dictum that a function must have exactly one entry and one exit point has led some to scrupulously avoid having more than one “return” statement in a function.

If all of the statements from some point onward in a function depend upon some condition and one is avoiding a short-circuiting “return” statement, one will naturally wrap the statements in an “if” test so as not to inappropriately execute statements. Thus the statements whose execution is conditional will inevitably get farther and farther from the test of that condition, impairing the readability of the source code.

Hallmarks of excessive nesting:

• There is a “then” part, but no “else”.
• Every statement is wrapped in an “if” statement that does nothing but confirm that a particular value was or was not returned by the immediately preceding statement.

Techniques to avoid excessive nesting:

 

1. Instead of writing this:
   •    if (b1) {
   if (b2) {
      if (b3) {
         ...
         if (bn) {
            S;
         }
      }
   }
 }
   • Do this:
     if (b1 && b2 && b3 && ... &&& bn) {
   S;
}
2. Instead of this:
   rc = f1 (x, y, z);
if (rc == NO_PROBLEM) {
   rc = f2 (x, y, z);
   if (rc == NO_PROBLEM) {
      rc = f3 (x, y, z);
      if (rc == NO_PROBLEM) {
         ...
         rc = fn (x, y, z);
         if (rc == NO_PROBLEM) {
            S;
         }
      }
   }
}         

   Do this:

   rc = f1 (x, y, z);
if (rc != NO_PROBLEM) {
   return;
}

   rc = f2 (x, y, z);
if (rc != NO_PROBLEM) {
   return;
}

   rc = f3 (x, y, z);
if (rc == NO_PROBLEM) {
   return;
}

   ...

   rc = fn (x, y, z);
if (rc != NO_PROBLEM) {
   return;
}

   S;

   Better yet, if you are writing in a language like C++ or Ada that supports exceptions, have each of the called functions raise an exception on error instead of returning a value that must be checked by the caller (who may or may not do a necessary check). Then you can simply write the vastly more readable:

   // Each of the following statements may raise an exception:
f1 (x, y, z);
f2 (x, y, z);
f3 (x, y, z);
...
fn (x, y, z);

   S;

Copyright  ©  2008 Possum Technologies, All Rights Reserved.

Legibility of sans serif typefaces

Problem: Illegibility of sans serif typefaces, especially when proportional spacing is used between characters.

Example: I have actually misinterpreted the following because the typeface used lacked serifs:

Insufficiently distinguishable text
Actual text	Misreading
clark.net	dark.net
modern	modem
Ill	111? III?
Double Churn	Double Chum
makefile.lvl	makefile.M

Objection:To be fair, legibility problems do not only afflict san-serif type. I have a file named “bsd-style.txt” that I always first misread as “bad-style.txt” when it is displayed in the Courier font.

Copyright © 2008 Possum Technologies, All Rights Reserved.

Avoiding unnecessary branching

Practice: Avoiding unnecessary branching.

Example (in C):
   if (c == 'N')
   {
       b = TRUE;
   }
   else
   {
       b = FALSE;
   }

Discussion: Since C inherited the conditional expression from Algol 60, we could write instead:
   b = (c == 'N') ? TRUE : FALSE;
But even that is over-complicated when we could—and should—write:
   b = c == 'N';
Besides being simpler, this avoids branching, resulting in smaller and faster generated code.

Objection: It is convenient to set breakpoints on the “then” and “else” alternatives of the “if” statement when debugging.

Answer: One can break on the assignment statement and examine its result.

Copyright © 2008 Possum Technologies, All Rights Reserved.

Comparing booleans

Practice: Comparing a boolean literal to a boolean result.

Example (in C): Let b be some expression having a boolean value (say, v1 > v2).
   if (b) ...

is better than

   if (b == TRUE) ...

and

   if (!b) ...

is better than

   if (b == FALSE) ....

Discussion: Booleans are sometimes referred to as “conditionals” in pre-ANSI C and have the type LOGICAL in Fortran.  The ANSI C standard guarantees that the result of a comparison always returns either TRUE (1) or FALSE (0). So were we to write

   if ((v1 > v2) == TRUE) ...
we would be comparing v1 and v2, which comparison would result in either TRUE or FALSE, which is fine, but then we would be further comparing that TRUE-or-FALSE result with the literal boolean value TRUE, which adds nothing useful to the more succint
   if (v1 > v2) ...

Objection: Some suggest that comparisons of boolean results with TRUE or FALSE is more readable.

Answer: Were
   ((v1 > v2) == TRUE)
more readable than
   (v1 > v2),
it follows that
   (((v1 > v2) == TRUE) == TRUE)
would be even more readable, and
   ((((v1 > v2) == TRUE) == TRUE) == TRUE)
more readable still, with further “improvements” in readability left as an exercise to the reader.

Copyright  ©  2008 Possum Technologies, All Rights Reserved.