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

Quality

[mfh]

he has a lot to say about Quality Assurance in the software world

Quality Assurance in 4 easy steps!

Dear Managers,

1. Listen
2. Close your mouth
3. Plan everything around #1
4. Profit!!! (notice there is no line with ??? because you listened!)

Re:Quality

[mfh]

And what then when the customer wants some hard evidence about what has been done? What then? What will you provide to them? How does your irrational hatred of managers actually assure quality in concrete steps?

A good manager does all the detail work and keeps track of everything. My post was about what they haven't been doing much of lately.

I don't hate managers, and to suspect that I might by reading my previous post means you failed to understand it.

Quality in business comes from many different people in any given project. Software quality can be adversely affected by morale, and you guessed it -- programmers have some of the lowest morales in the business world today; they are often not respected by management, they have the highest workloads, and they have no time for social lives.

If managers listened, and remained silent or inquisitive instead of arbitrary or antagonistic, software quality would be up.

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.

Re:Quality

[fyngyrz]

Quality Assurance in 6 Easy Steps:

1. Fire the managers
2. Fire the beancounters
   (steps 1 and 2 may be reversed if required)
3. Fire anyone who even mentions the word "committee"
4. Keep labs open 24/365. Apply metered, but 100% flexible, work hour rules for programmers (ie, "You have to work 40 hours/week, but it doesn't matter which 40 hours.)
5. Provide superb comfort and amenities to programmers
6. Create significant bonus program tied directly to number of problems found in each programmer's code per release cycle. Zero problems, max bonus, more problems, less or no bonus. Stir to taste.

Enjoy good results.

Re:Quality

[penglust]

Been there, done that. I could not agree more. But I have had a number of good managers in the past. Did a stint as manager myself at one time. I backed off because, like you, I just plain like to be productive and I think like an engineer. This may it difficult to deal with those above me.

My direct manager right now is acutally one of the best I have seen. The other 3 or 4 layers above are lost and clueless most of the time. Their buzz word at the moment is ISO 9000.

I think your comments bring up another issue. F**k up move up is often not just a saying. I have made friends and lost friends in the past for my opinions but if one of my fellow programmers is just plain incompetent, lazy, or an ass hole then they need to go. I don;t encorage moving them to get them out of my hair. I have done this before and somehow I always ended up having to deal with them again.

There is also the type that are just biding their engineering time till they can become a manager. I have generally found these guys to be less than worthless. They are usually garanteed to make the worst managers.

These are the criteria I usually find good in a manager and tried to use as one:

1. Have a good broad software background. If working at the kernel level (including driver) have a basic understanding of hardware

2. Understand how software impacts the potential customers and their needs. Books have been written on this, most of them wrong.

3. Know your employees and their stengths and weaknesses. Use this to build a team that can and will perform.

4. Trust the team but keep track of everything anyways.

5. Process is a must but it should be pretty lightweight. Make it enforcable and do not waiver in ensuring the necessary pieces occur.

6. Insulate your engineers from most of the stuff above. Not all, just most of it. Usually controlling the flow will suffice (often this involves rumor squashing).

OK enough for now.

Unit testing?

[JohnGrahamCumming]

It's quite surprising to me that there's no mention here of unit testing, or any sort of automated testing where the engineers who wrote the code actually write tests.

It should, by now, be clear that "code that doesn't have tests, doesn't work", and that if XP has done anything for us, it's to focus on writing tests. I've seen this in action and it works.

John.

Re:Unit testing?

[bloggins02]

Unit testing is essential, but it's not a panacea. In particular, beware of two pitfalls:

1) "The unit tests passed, so it works." This assumption is flawed on several levels. First, and most fundamentally, even if all unit tests pass, there is still the issue of whether your software works as a whole. Software often has "emergent logic" and UI scenarios that are difficult or impossible to test (after all, that's not what unit testing is for, but some people seem to think it is).

Second, just because a test passes, doesn't always mean the API works. This is especially important if you didn't write the tests yourself. Just because a unit test CLAIMS it tests X, doesn't mean it does. Is the test complete? Any false positives? Is the test just a skeleton that was intended to be implemented later but never was? I've had all these bite me in the past.

2) "That particular test has NEVER passed, so there's something wrong with the test. We just ignore it now." Bzzzt! Wrong! There's a REASON it never passed. It's either not implemented properly, just a stub that fails waiting for someone to write an implementation, or maybe you just think the feature it tests actually works. Look closer. The test might be trying to tell you something.

If you are careful with unit tests, they can be very rewarding and useful (especially for regression testing, where they are invaluable), but put too much confidence in them or depend on them to do the kind of overall testing they were never designed to do, and you will fail long before your first test does.

Re:Unit testing?

[Unkle]

But that's really the reason it's not done all that often. Developers think that the unit test will be a waste of time. The problem is, nobody codes perfectly. Finding a bug during unit testing is much better than finding it in design validation testing. Indeed, on many projects I have worked on, issues that could have been found with adequate unit testing were not found until after release.

Unfortunately, when schedules get tight, it's things like unit testing (and testing in general) that get cut. The more emphasis we get on the importance of QA the better our industry will be.

Good code...

[TrollBridge]

...isn't just for end-users! If you anticipate that others will be working on future versions/releases of your software, good commenting can make the job SOOOOO much easier for the next codemonkey.

I'd say commenting is doubly important in OSS projects, as it involves many sets of eyes trying to comprehend what you coded.

Re:Good code...

[Dr. Evil]

Commenting must be 100% accurate else it is detrimental to understanding the code.

Sometimes code changes don't result in updated comments...

Once I find an inaccurate comment in somebody's code, I have to start rewriting or deleting all the comments because I can't trust them anymore.

Re:Good code...

[johannesg]

That, and good naming of variables / functions / classes. To clear up any possible confusion: that means that the name has some bearing on what the thing in question is doing for you...

Recently I had the misfortune to wade through a few hundred kilobytes of Java that was written by someone who thought he should 'abstract' everything as much as was humanly possible. Sounds good, right? Well... It turns you can do a lot of harm that way, too. I don't think he had a single function in there that _wasn't_ called something like SetProperty(), GetValue(), DoFunction(), etc. There was absolutely no way to guess what it was doing based on the name of the functions. Naming of classes and variables wasn't much better. After looking at it for a couple of hours I don't think I could have guessed what it was trying to do if I hadn't already known that beforehand.

So, next time you are writing software, feel free to get in touch with reality and name stuff after what it is supposed to be doing. Nice long names please, no abbreviations unless you go over 30 or 40 characters. Down with CmtPmt2Db(), down with SCUPD(), and down with GetPropertyValueInterfaceCaller()!

Because, be honest: those mean nothing, while CommitPaymentToDatabase(), ScreenUpdate(), and GetXLocation(), have intuitive meanings we all understand...

Re:Good code...

[gidds]

Comments tend to state the obvious and not tell you what you really want to know.

This is a reason to write better comments, not to avoid them completely!

Of course comments that are flippin' obvious, or wrong, do no good to anyone. But some sorts of comments can be incredibly helpful:

• Big-picture comments. Explaining what this function, method, class, file, or interface is doing; how it fits into the app or system; important design decisions. Also authorship and date information, if that's important.
• API comments. Describing the implicit (or explicit!) contract that a function, method, class or whatever has with its caller. When you should be calling this code, what the caller needs to have set up beforehand, what the code guarantees to do in return, any gotchas.
• Section comments. Within long functions, just a few words every 10-30 lines, breaking it up into logical sections, can make it much easier to understand the flow, or find the particular section you're looking for.
• Here-be-dragons comments. Describing tricks, shortcuts and other hacks. Better to make the code clear and obvious, of course, but there are times when a clever technique or bit of magic is needed, and for those rare occasions, a few words of explanation can make things so much clearer -- and prevent someone ignorantly 'fixing' it later!

Of course, there's some overlap. But these are the sorts of things that can make code so much easier to read, and don't take much effort to maintain. The big-picture and API comments tend to be common practice in literate languages like Java (JavaDoc) and Perl (POD), but too many people don't follow it -- and even where those comments aren't extracted automatically, they can still be incredibly useful.

My rule of thumb is: Try to make the code itself obvious. And comment everything else!

Alan Cox

[Anonymous Coward]

Who cares about what Alan Cox has to say? He's soooo 2.4

Testing is good

[TreadOnUS]

But the real key is reducing the number of defects introduced into software. Testing only finds existing errors. If the number of errors are low from using good requirements, design and development practices then testing becomes less expensive and time consuming.

Testing and releasing software

[plcurechax]

My employer produces a large-ish software package, with 10 years of history and a small, 2-3 people, development team. Since I joined we have made massive strides in automating the build process, include some unit tests, and a few smoke tests in an automated process.

Well, the effort paid off. Before we supported one version of HP/UX, and one release of Linux, now we support HP/UX (still a pain), and 4 looking at going to 6 Linux version/distributions and it is less work to produce a release now than ever just a year ago.

Tools like automake, autoconfig, libtool, cvstrac and of course cvs have made my life bearable.

Re:Code review and pair programming

[ZorbaTHut]

Funny, that. I recently started working at a company with mandatory code reviews. Here's a list of my recent experiences with it:

1) Checked in code. Spent fifteen minutes justifying design decisions. No changes made.

2) Checked in code. Code contained horrible horrible bug. Code reviewer didn't see it.

3) Checked in code. Defended my design against several more computationally expensive suggestions that were also more complicated. No changes made.

4) Listened to a friend gripe about having to spend a DAY AND A HALF repeating design reasons and fixing bugs introduced by his code reviewer "cleaning up" his code.

5) Received company-wide email about a build that flat-out didn't compile - apparently someone hadn't bothered compiling a patch, and had sent it to a code reviewer, who likewise hadn't bothered compiling it before authorizing it.

Now I'll admit that there are also a whole lot of "well, it only took five minutes, so it wasn't much of a waste" cases. But so far I haven't heard one person talking about how useful the mandatory code reviews are.

Maybe it's just an artifact of the kind of programmers working at this company, or the kind of code being worked on, but so far code reviews have been a net loss in my experience. I've taken to doing major changes in my own personal branch of the repository (which doesn't enforce the code-review requirement) and in a month or two I'll have 3000 lines of code for someone to look at - but at least I won't have nickel-and-dimed them to death with 120 100-line code reviews, 3/4 of which I will inevitably end up deleting entirely.

Note that I'm not saying "code reviews are bad" - what I am saying is that there's a time and a place for just about every technique, and there's also a time and a place where each technique is worse than useless. Pick your battles and pick your tools.

Code validation tools...

[tcopeland]

...are nifty. They can catch all sorts of stuff and produce lovely reports - or, well, at least functional reports. And running them nightly - or hourly - helps to ensure the code won't get out of sorts.

PLUG: Need to check Java code? Try PMD!

Keeping prototypes just that

[mark1348]

You can't help but be frustrated when dealing with projects that were obviously "proof of concept" which then evolved directly into the actual "product". Hard to resist but just plain stupid. I wish more open source projects had strict standards.

Re:2 words

[Unkle]

I actually had a coworker marked down on his yearly review last year for wanting to write re-usable code. Our manager's (very VERY flawed) opinion was that, though it might be nice to have the re-usable code, just write it for this specific task because it's just easy and fast.

The kicker is, this year that same manager wants to re-use the code that my coworker was origionally going to write.

There are different types of code reviews...

[Richard Steiner]

We used to implement code reviews at my former workplace, but they were more "sanity checking" peer reviews than anything else. They didn't take very long, and it gave one or two other people a chance to see how understandable or generally logical the changes were.

That type of thing doesn't work as well for large changes, but we found that for small ones it sometimes can be a useful thing.

Write the tests *first*

[wowbagger]

More importantly, write the tests FIRST. Then write the code, updating the tests for anything that is identified during the coding.

This has several important benefits:

1. You have to DEFINE what the module is to do so that you can write the tests. Granted, the first pass for the "tests" may simply return "failed" until something is written for the module, but at least you will have a chance to think about what you should be testing.
2. You actually DO write the tests, rather than blowing them off. If your manager says "Why aren't you working on $blarg?" you can say "I *am* working on $blarg" since the first step is writing the tests.
3. As you get funtionality working (as demonstrated by the tests passing) you can quickly determine if a later addition to the code breaks the working feature - and fix it while the change is still fresh in your mind (and hopefully BEFORE you commit your changes to the mainline code path (you ARE using a source code control system, aren't you?))
4. You can automate the testing of the system.

Re:2 words

[johannesg]

Ha, that's nothing. Long ago I used to work for a company that thought it was a good idea to NEVER reuse code because then you would reuse all the bugs as well. OTOH, they reasoned, if you wrote it from scratch you wouldn't be copying old bugs, thus this was a safer thing to do.

I'll leave the results as an exercise for the reader...

Good practices

[vinukr]

These are some things i guess is necessary for good software
1) Reviews at all stages.(Reqs/design/dev)
2) While at development, u sure must know whats the most efficient way to code a design (which libraries are more suitable etc)
3) Unit testing and Integration testing (when the project is huge)

Some practices that managers can really use to take the pressure off the team
1) Try giving buffers to the team (seriously, it works)
2) Proper Code management (Lotsa rework and pressure come due to lack of this)
3) Proper tracking and status updates to the customers

MBA?

[Anonymous Coward]

So now we're taking software writing advice from PHBs now? :)

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."