Alan Cox on Writing Better Software

Andy Gimblett writes "Alan Cox recently gave a talk in which he discussed some current and emerging techniques for producing higher quality software. Some of these will be familiar to Slashdot readers, such as validation tools, type checking, etc, but others seem heavily influenced by his recent MBA. In particular, he has a lot to say about Quality Assurance in the software world, and the kinds of things we should be doing (and some people are doing) to make better software. Story and lots of quotes at Ping Wales, and video at IT Wales."

Comments

Re:Quality

[acvh]

"no time for social lives"? like they would know what to do if they did?

but seriously, good managers manage. Bad managers threaten, cajole, bribe or whine. software is either a product, which means that management is monitoring to be sure the product is what they can sell; or software is a tool, in which case the manager must ensure that the tool works.

either way, successful software is a combination of good programming and good management.

WHY, not what

[wowbagger]

The single best rule of comment is "Comment upon the WHY, not the WHAT".

Don't say:

double sum = 0.0; // zero sum
for (i = 0; i < len; ++i) // all samples
{
double signal = buf[i]; // get value
sum += signal*signal; // add signal^2 to sum
}
return sqrt(sum/len);


say:
// Compute RMS average of signal -
// compute the sum of the squares of all values,
// then compute the mean (sum/len), then the
// root of the sum - hence Root-Mean-Squared

double sum = 0.0;
for (i = 0; i < len; ++i)
{
double signal = buf[i];
sum += signal*signal;
}
return sqrt(sum/len);

In other words, tell me WHY this code added the square of the signal, not THAT it added the square of the signal.

Moreover:

1. Every directory of the project should have a purpose, and should contain a short README describing the purpose of the code in the directory.
2. Every file should have a header that describes the purpose of the file.
3. Every function should have a header describing the purpose of the function, as well as any inputs and outputs (including global, static, and class variables), any exceptions thrown, and any assumptions made.
4. Blocks of code within a (large) subroutine should have a descriptive block comment describing the overall goal of that block (e.g. "Now we walk the list of conversations and update the call stats").
5. Comments on a line of code shouldn't be needed normally - the code should speak for itself. Only pretty tricky things ("use a shift and add rather than a multiply as this saves 3 clock cycles") should need a comment at end of line.

If more folks would follow these rules it would be a HELL of a lot easier to follow their code.

NOTE: If you can say it in the code, do so - if you can specify the exceptions to your function via a "throw(int code)" type statement, then do so rather than using a comment.

Remember - the code tells the COMPILER and the programmer what is going on, the comments tell the programmer WHY it is going on.

Re:2 words

[sootman]

And for those who don't like exercise, I suggest Joel. Samples:

"The idea that new code is better than old is patently absurd. Old code has been used. It has been tested. Lots of bugs have been found, and they've been fixed. There's nothing wrong with it. It doesn't acquire bugs just by sitting around on your hard drive. Au contraire, baby!... it has grown little hairs and stuff on it and nobody knows why. Well, I'll tell you why: those are bug fixes.

One of them fixes that bug that Nancy had when she tried to install the thing on a computer that didn't have Internet Explorer. Another one fixes that bug that occurs in low memory conditions. Another one fixes that bug that occurred when the file is on a floppy disk and the user yanks out the disk in the middle. That LoadLibrary call is ugly but it makes the code work on old versions of Windows 95.

Each of these bugs took weeks of real-world usage before they were found. The programmer might have spent a couple of days reproducing the bug in the lab and fixing it. If it's like a lot of bugs, the fix might be one line of code, or it might even be a couple of characters, but a lot of work and time went into those two characters. When you throw away code and start from scratch, you are throwing away all that knowledge. All those collected bug fixes. Years of programming work."