Slashdot Mirror
Ask Slashdot: On Good Software Design Processes
Marko Rauhamaa asks: "I'm a software manager in a medium-size technology company. Today I ran into a professional argument with my superiors about our company's software design process, which, I suppose, is fairly standard: The software team is to write one or more MS Word documents that have predefined section headings. The documents should describe all aspects of the coding phase that is about to begin. Then the documents are peer-reviewed, polished and submitted under document control. Questions: What kind of design process do the successful free-software projects have (Linux, gcc, Apache, XFree86, etc)?
In your experience, how often are design documents revisited after
the project? Have design documents helped in technology transfers (that is, have they been more helpful than the source code alone)?
Are engineers good at writing design documents? Have you been able
to read design documents written by other engineers? Have old design documents been kept up to date with the changes in the implementation?
Has the quality of your products been better because of design
documentation?"
Most places you work, there will be some formal "process" that is perceived to let the factory model of production be applied to software development. There are two parties that have a vested interest in this: those that push a particular design process (typically CASE tool vendors), and those that want close estimates and the ability to interchange designers and programmers at will (managers).
Unfortunately, ANY such process, while it may have it's benefits, isn't perfect. True wisdom is knowing when "the Process" doesn't apply.
A few thoughts:
1) You can't think of everything up front, no mater HOW GOOD you think you are. This only works for small systems and systems with few well-defined intercomponent interfaces. You'll struve for the latter, but you won't get it first time around (or even second), but you'll get closer every time.
2) Anything which divorces implementation from design runs the usual risks associated with multiple views of the same think. Code often gets out of sync with UML, for example, though this can be audited for, and incrementally corrected. I do this CONSTANTLY. It is a form of overhead, though, and must be taken into account.
3) While metrics are great for predicting project side and time, collecting them often brings up a Heisenberg Uncertantly Principle effect: the mere act of measurement distorts that being measured. In some cases this can slow down the productivity of your best people to that of the mean -- that's expensive because you're best are likely an order of magnitude more productive than your worst, and so generate far more metrics to collect, even though many of them are useless. This flies directly in the face of rapid prototyping where the goal is to make things with the intent of throwing them away.
4)Don't waste your time auditing for mistakes that you are very unlikely to make. Of course, you need to collect some metrics to find out what mistakes each individual DOES make, but, in the absense of these, most programmers and designers have a good idea of where the mine fields are and ALREADY take extra care.
5)Don't come up with a "one size fits all" audit procedure. Some things are hard to audit for, and not all reviewers will have the skill to do this.
6)Do try to get the machine to do most of the work. If there is a "coding style standard", invest in a prettyprinter program instead of having people count spaces. Reading other's code isn't the same as iteratively developing your own. For example, I like my code to be fairly dense, so more of it fits into an editor window. This way, I can review the last thing I coded for correctness while I code the next one.
7)If something is too error-prone for some to use, but a great productivity booster to others, do let those others use it with the caveat that with this freedom comnes responsibility.
8)Remember that programmers and designers are not interchangable - the difference between the best and worst will be on about one order of magnitude (i.e. a factor of 10). Do not fall into the trap of hindering your best because the average has difficulty understanding a particular technique - if it is well documented (say anything in "Design Patterns", or even "The Art of Computer Programming" (I'm dating myself here), it should be fair game, and the onus on the neophyte to learn from it.
9)Remember to not etch process in stone. Third-party code you license will likely NOT follow your coding standards, and woe unto him who changes it when it comes time to integrate a source upgrade. Neither is it perfect. Don't trust the documentation -- read the code. If I had a dollar for everytime I say code not match documentation, I'd be rich.
10)Document what matters, and keep it short. The basic idea on a design or sub-design should be expressable in no more than a page or two. Don't linger on unnecessary details unless it is a code API.
11)Be flexible. While your process may be best 95% of the time, you will be burned when you try to apply it the other 5% of the time.
12)Know when to violate process, and how to weigh the risks of doing so. There is certainly risk here, but it is not infinite, and it might be far less than the risk of not violating process. This usually happens when (a) schedules are tightened unexpectedly, and/or (b) you run into the 5% scenario that your process handles badly.
13)Don't get bogged down in overhead. If you make a one line change that corrects a clear oversight, don't fill in a three page form, unless the oversight looks like it may be a systemic problem.
14)Finally, never assume anything. You're always playing the odds. Learn to manage uncertainty.
In Liberty, Rene
That said, this question touches some deep issues that I'd like to try to comment on.
The main thing is that different projects have different needs in the design process. In most of the projects that I've worked on, learning how to do "X" is more of the thing than actually writing the code to do "X." This is probably because I tend to choose "fun" projects. If I were banging out yet another goddamn middleware transaction thingy, I'm sure that more formalized "processes" would make more sense.
As it is, the usual processes that get applied assume that it's already understood what is needed and how to accomplish that. One common thread to many of the horror stories I've read is the churn-mill of changing requirements and specifications. To me, this is a natural consequence of not knowing what you're doing to start with.
And not knowing what you're doing when you start is necessarily a problem, especially if learning is a part of the process. This is perhaps one of the greatest things about free software - it's a learning-centric process.
I think good design is just as important in the free software world as elsewhere, but it manifests itself in different ways. Usually, there is more than one competing project in a given space. Ideally, the one with the better design will win more developer hearts and minds. This is of course not always the case - often, a program will succeed in spite of its bad design, or perhaps because of it (a certain popular mail transfer agent certainly comes to mind :).
And the other thing about free software design is that it's often a whole lot simpler than comparable designs from the commercial world. Free software rarely comes with chrome-plated tail fins. In my opinion, the mark of a truly outstanding design is that you don't even notice it's there. Take the sockets API for example; compare it with any other networking API out there.
I guess my point is "different strokes for different folks." The fact that free software turns out such good work even though there's no formal design process certainly proves that the formal techniques are not necessary, and suggests that the formal people are missing a big piece of the puzzle. But for successfully executing needlessly complex projects by an army of more-or-less competent programmers, I'm sure they are an indispensable communications tool.
Maybe some day the software engineering crowd will work out tools and processes that work so well everyone will use them, even in free software. But I'm not holding my breath.
LILO boot: linux init=/usr/bin/emacs
In summary, while by no means am I suggesting that doing quality design work before the software is written is a bad idea - I'm just pointing out that in my experience, the only projects that can be designed to the last detail are projects you'd most likely find exceedingly uninteresting. Most software I've written that's worked out well has had a highly iterative quality to it - you design a bit, argue in front of a whiteboard a bit, code a bit, demo a bit then repeat. Certainly a good rule to remember is this: The longer development goes on for without the client/customer seeing the product (even as a demo/prototype) the larger the potential for the project to diverge significantly from customer expectations becomes.
there are two kinds of people in this world - those who divide people into two groups and those who don't
Correct. Documentation takes about 40% of the time.
Design takes about 50%.
And implementation takes about 60%.
These are not performed concurrently, which is why software is always late. Except when you leave out the design phase... But we all know what kind of software that spawns.
-- What you do today will cost you a day of your life.
What you describe doesn't sound like a development process at all. It sounds like a documentation burr... A development process is a pretty ethereal animal (those that may or may not exist, depending on whom you ask).
I've personally not worked on open source projects (yet) but I imagine that they are vastly different than any commercial effort. Seems to me that managing gratis developers is like herding cats - if you try to control them, they'll simply leave.
But, I would strongly recommend Steve McConnell's book on Rapid Development, and Code Complete while you're at it.
The RD book - well, eat it. Read it cover to cover twice, and with that knowledge in your head, use what fits your project and developers.
Your people may like to do thorough design up front, and follow the traditional 'waterfall' process, but that doesn't stand up well to changing specs.
Incremental development seems to work well where I work. We have a small team, and in-house users, so feedback and even design changes can happen pretty quickly..
You'll need to look at the risks your project is facing as well as a number of other factors - i.e. do you subcontract, buy COTS stuff, use strict CM and are you subject to stringent V&V?? Who are your users, how skilled are your people? Look where you fall on the Capability Maturity Model (1.1 release) hierarchy and how you rank per ISO 9000-3. If nothing else, you'll get some ideas.
As you can guess, there's a huge number of variables that go into defining a successful process. The Software Engineering Institute at Carnegie-Mellon University may prove helpful, but I would recommend the aforementioned book (RD) first.
-- What you do today will cost you a day of your life.
Don't bury innovative ideas by making the "process" of software-development water tight. Though the project will accomplish it's goal, it is usually in the project's best intrest to be open to development of primary ideas after the launch. Software devlopment can be seen like the making of a Jim Carrey movie. Sure, you can force Jim to follow the script to the letter, but if you keep him from doing his last-minute improvisational work, you loose the lifeblood of the movie (and wind up with shit like "The Cable Guy").
:)
Maybe I just need to get some sleep
I worked at a small software company (this one was VERY small) and we obviously had nothing that rigorous.
You know this, but I'll just go ahead and say it anyway: Unless you're writing "Hello world" you ALWAYS do a thorough design first. With my company, that meant everyone standing around a white board armed with markers, arguing about how to design it. Once we had our design up on the white board we would leave it there and divide it up into pieces and hand out the pieces.
Things were always informal with a small group, and we never had to worry about miscommunication. With a big team the plan you described sounds like a good one to me.
Of course, I think they should always start with a couple hours around a white board.
Vidi, Vici, Veni
This isn't the best way to design software, but it seems to be a common method.
--Shoeboy
As a Software QA engineer, I can say that design documents are critical. How am I to know that the software is working correctly if I don't know how it's supposed to work? For those that think this is trivial, think back to last weeks "life or death software" article.
Developers don't like doing design documents. I don't blame them for not wanting to write the specs until after they're coded in. But it's important. They keep everyone on the same page, and prevent developers from putting in the app what they think should be in it.
Design documents allow more than one person to code an application at the same time. The smaller the project, the less "formal" the docs need to be, but they need to be there. Even if the app is just a simple text editor, if one developer is thinking "vi", and another "wordpad", you're going to have problems.
A story: Two days after a major application is released, customers are screaming that the autosave feature is overwriting unrelated files. Someone traces the cause down to a combination of autosave and the autospell. PHB calls the tester into his office and demands to know why the bug wasn't found previously. Tester explains that the autospell was never in the specs, and had no idea it existed, and so could not test it. The PHB, the idiot that he is, fires the tester, and gives a bonus to the developer that wrote the autospell.
A Government Is a Body of People, Usually Notably Ungoverned
I've worked on dozens of s/w projects ranging from solo assignments to enormous multi-headed monsters involving hundreds of people doing coding and validation. I've noticed a method which seems to work fairly well for a variety of project sizes. Of course, YMMV.
1. Don't get tied up in writing a bunch of specs up-front. The spec-it-all-first method almost always results in sub-optimal implementations and reams of out-of-date documentation.
2. Get a handful of senior coders (and one or two customers of the product, if possible) in a room and have them architect a skeleton of the project on the whiteboard. Get a junior coder to take notes. These minutes are your first "design document".
3. Figure out how to partition all of the pieces from #2 into nice libraries and data structure definitions. Define the basic functionality of the libraries without specifying the exact interfaces (which will be wrong for the first two iterations).
4. Prototype and re-prototype the implementation, allowing the developers to work out the interfaces between themselves. Get customers to try out the prototypes.
5. Schedule a "get well" phase of the project where code is cleaned up and interfaces become mostly frozen. This is the ideal time to document the "final" interfaces, data structures, and algorithms. Hold peer reviews of code and documentation. Discipline is vital here if you want a documented design.
6. Productize.
7. Maintenance mode. If you can find a way to keep the documentation up to date from this point on, please let me know how you do it.
While any document which isn't auto-generated directly from the code will become out-of-date, getting most implementation details figured out by trial and error before writing an official document will make it more accurate with less maintenance overhead.
I've seen a lot of projects fail miserably when management spent too much time trying to spec everything up front. One group in my company has an offical flow which goes something like this:
1. Write an Market Requirements Document (MRD)
2. Review the MRD with a lot of people, many of whom have no idea what the market really needs but have a lot of opinions about how the MRD should look.
3. Revise the MRD based on the review.
4. Write an External Product Specification (EPS). This defines every feature which is to go into the product that is visible to the user (as well as how it is visible to the user).
5. Review the EPS with a lot of people.
6. Revise the EPS and get "buy-in" from all of the
"stakeholders".
7. Write an Internal Product Specification (IPS). This defines all internal modules and most of the data structures and algorithms. Note that usually this is published before any code has been written.
8. Review the IPS with a lot of people.
9. Revise the IPS until everybody is happy.
10. Start writing code (usually about 4 months after the process has started).
11. Find out that the customer has already started using another product from somebody who has followed the first method above.
12. If the other product is from another group in the same company, try to kill that product via political means.
13. Finish coding up something which is grossly inefficient and doesn't meet the customers' real needs, but that meets most or all of the items in the MRD, EPS, and IPS.
Ok, maybe some of that isn't in the offical methodology...
Finally, there are many factors besides design documentation which help to make or break a project (having talented people seems to be most important); so pick your battles if you're going up against management edict.
Once apon a time, I used to teach this stuff. Doing it is much more fun.
/. as many other respondents have previously noted.
Design Documents are just part of the whole theme of a well engineered software system. Much depends on the system being constructed and what it needs to interface with. I've written and used extremely detailed design documents (this BIT goes here, that BIT goes there) for a project where all the pieces were being implemented in different geographic locations. When the thing was assembled it even worked! On the other hand, I've been gratefull for a very brief, high-level 'how this fits into the big picture' design statement that described a report system that just sucked from zillions of different data sets that were previously defined elsewhere. So it depends on what the goals of the project are.
In 'open' software, I'd much rather have sections of documentation inline with the code that say things like, "At this point we know XXX and we're now going to YYYY." Tell me the high level story as it is less apt to rot over time compared to the minutia.
Finally, Design Documents that are used will be updated. DD that are just worthless trash from the outset, no one will care if they further get bit rot.
If you have not read Fred Brook's book, "The Mythical Man Month", now would be a good time.
Your question certainly is bigger than a ask
P.S. Revision control and MS Word documents? Doesn't the constant change of format of MS doc's cause you to worry that your documents will not be readable later in the products life? I'd be using "Plain Old Text" as ISO-Latin1 is not apt to go out of style anytime soon.
Requirements Documents. Can't live with them, can't live without them, can't ignite them and dance around their burning ashes.
::Loud screams and coders jumping out windows::
The requirements document of the project I just spent 80 hours a week working on for the entire summer was a source of so much grief that I get queasy just thinking about it.
Basically, the customer handed us over 1000 pages of documentation and said, "This is the best requirement document that has ever been written. You shouldn't need to ask us anything about it, because it's so damn PERFECT!"
Needless to say, it was NOT perfect.
It looked all fine and dandy on paper or on design flowcharts, but actually trying to write compliant code was a nightmare and a half.
But wait! Here comes the frustrating part!
Every time we tried to talk to the customer about something we needed to implement that wasn't in the requirements document, the response would be...
"Read the requirements document!"
-
Step 1: Screw design, charge right in. Start coding immediately. Throw it all against the wall and see what sticks.
/dev/null before I even think about real design. The designs I've been most proud of were always version 2.
Step 2: Type "rm *"
Step 3: Write the design document.
Seriously, I've been amazed what you can find out by simply trying to code something up. I find that I can avoid so many horrible errors by throwing up some code that I know will go to
The cake is a pie
In my experience when organisations get religion about documentation, they tend to produce lots of useless documents. The key documentation to produce is the maintenance manual and a users' guide. Keep both short and up to date.
Historical documents are useless eg those produced by various project phases, except for butt-covering in bureaucracies.
At the program level, document the interfaces to the programs and the expectations and assumptions, again quite concisely.
Some great reading on development is at c2.com/cgi/wiki?ExtremeProgrammingRoadmap.