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

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!

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.

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.

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

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.

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.

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

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.