Documents First Code Later
Documents First Code LaterTraditional software development methods suggest creating documents that describe the requirements and the design or the system before the code is written. In practice, requirements documents are more common than design documents, since the business people can read and write the requirement documents, but they neither read nor write the design documents. So, developers tend not to write them. But anybody who has taken a software engineering course knows they should.
But should they? XP says that design documents are unnecessary. In fact, it says that requirement documents are not always necessary, and that requirements can be transmitted orally from the customer to the software developers. There are clearly different points of view on this subject. Wiki has much more than its share of XP fans. Let's hear from people who like documents first.
Having no documentation is IMHO indefensible. I have yet to see an example of a large system that is learn-able without documentation. XPers are not free with code examples so it's difficult to judge their claims. The one example we do have is the unit test framework, which fails miserably in being self documenting. Everyone on my team that has used it has had to ask me how to use it. None were able to grok it on their own.
But I believe any documentation should be in the code and extracted from the code. My personal style is to create interfaces and document the classes and methods. By doing this I have to think through the whole system and how it works. Any risk points are prototyped. Next is a phased implementation in conjunction with unit tests. -- AnonymousFool?
[What is meant by "learn-able"? Most users for most systems have never opened or even seen a users manual, yet some how they managed to learn to use the system. Most developers have never seen a system's requirements documents nor design documents, yet they are able to modify it. In SDLC theory, these documents have value. In practice, they are virtually unread.]
This is the exception that proves the point. Although there is extensive unit test framework documentation, team members prefer to simply ask someone who knows. We should strive to get good at such communication, rather than struggling to avoid it.
Actually it proves that the subsystem is not sufficient to be used by a good sample of developers. And I'm not sure where this documentation is, it's certainly not in the package itself. As there are many unit test frameworks out there maybe some are more documented others. The C++ unit test framework has/had minimal documentation.
We have many other far more complex subsystems that have good documentation where intensive per developer instruction is not required. There's not enough time in a year to explain 100 times to 100 people how a thing works. Good documentation all but solves this problem. Yes, documentation can get buggy and out of date, but I see no evidence that a general population of developers can internalize large code chunks such that it can be sufficiently understood. People have the same trouble reading unit tests, so IMHO they don't serve as good doc either. -- AnonymousFool?
I believe the top of the page was discussing design documentation written prior to the code. The previous discussion seems a little off track.
Where I work I am rarely asked for documentation, and of those rare occurrences half are just stalls - they know no documentation exists, and they're playing "critical path hot potato". I write documentation for one reason. It helps me think. When I do it, it proves its value to me time and time again. It doesn't matter if anyone (including me) ever reads it again. But it's a nice bonus when it is readable and helpful. So I strive for that, and in circular fashion, it's that striving that makes it a thinking experience. -- WaldenMathews
So this reminds me, a question for the XP folks: if I like/prefer/need diagrams rather than words, how to do put that into the code? -- AndyMoore
Why put either words or diagrams in the code? Why do you "need" them?
I found some answers/discussion in TheDesignIsTheSourceCode.
What kind of documentation is really lacking here? Sure, there is no user documentation in the same package as JUnit (if I recall correctly). But just a quick internet search gives you lots of guides for how to use it. So is there really a problem here?
First, XP says don't document, saying the code should be clear enough. This isn't true for the unit test which is a very simple subsystem. Second, very few developers will recognize the unit test framework as something public where there is possible more documentation available, so the end result for most people will be no documentation.
Maybe unit test tools aren't the best example for DocumentsFirstCodeLater, since "tool developer" documentation vs. "tool user" documentation is confusing things.
I guess I don't see this as everything is a tool from some other piece of software's perspective. The XP documentation rule should apply to all software.
I believe the top of the page was discussing design documentation written prior to the code. The previous discussion seems a little off track.
"Where I work I am rarely asked for documentation, and of those rare occurrences half are just stalls"
Very few people have the guts to ask. If it's there then there's no problem.
What is the cost of preparing and maintaining the documents compared to the value they provide? Yes, it would be nice if someone had written down the precise information I need in a well referenced location, but how much additional, unneeded information would have also been written to ensure the needed information was also captured? It is far more cost effective to obtain information on an as needed basis than trying to maintain all possibly needed information all of the time.
I've recently joined a company that is traditionally into the "design specification" mindset but up-front requirements are still communicated ad-hoc to the developers. I feel compelled to write a requirements document with use cases mainly because I know it is the only way that things won't get missed but also for the reasons that WaldenMathews, above points out - it's a thinking tool Deep down I also know that the document will not really be read an awful lot. Darn, I just wanna get on coding now! -- RussFreeman
Instead of opening up Word and typing in a Requirements document, why not open up the code editor and type in an AcceptanceTest? You will get the same thinking benefit and also have something that will be used again later.
Write those developer notes you'd normally write on paper on a wiki. Any time you are asked a question that you'd normally respond to by e-mail, write it on the wiki. Any time you learn something, write it on the wiki. The wiki evolves into documentation.
Concur. I think a lot of us have this pattern whether we admit to it or not. I use a lot of little docs that are easy to maintain. Sometimes I will have an ongoing "notes" file on the development of a particular component that gets changed three or four times in a day. Of course I have a daily log or the work I do, and my weekly reports are pulled from that. The client is paying for professionalism, and creating a lasting record of what worked as well as TheRoadNotTraveled is important in providing value for the client's moolah.
The other part of this is automation. The easier me make it to record design decisions and sketches and such things the better our overall docs will be, regardless of what part of the design and development cycle the documentation (verb) takes place. Being forced to use cumbersome UML tools and such things will not encourage engineering types to write things down. Automated tools that approximate the ease of use of pencil and paper will get it done. Suggestions, anyone?
Why should we be concerned with the quality of documentation, especially if it serves no purpose?
Hello? Hello? Are you paying attention? We're not talking about documentation that "serves no purpose," but docs that actually can be - and are - used. Reread this little section with an open mind and see if you understand better. If you still think the kinds of documents being described here are useless then support that theory with some reasoning, eh?
What purpose does recording my e-mail serve? I only see references to people saving a lot of text; I don't see any references to anyone ever using it.
If your emails contain certain technical details that aren't captured some other way (kinda bad in itself) then save them. Do the notes your scribbled to your local project Wiki have value? Save 'em. Save what has value; ashcan that without. C'mon - are you trying to tell me you can't see a principle here that is fairly easy to implement? You can't figure this one out for your own bad self?
Now: anyone with suggestions on how to make it easy to capture this stuff? Remember, nobody will write anything down if it's too tough. Make it easy and it will get recorded.
I wrote a couple of programmer-oriented documents on my last project, so let me explain them. Document 1 was describing a rewrite I was about to undertake on a small but critical piece of code that had degenerated to the point where no one who was there understood how it worked. I sent out email to several people who might know something about the code and/or the problem it was supposed to solve. I ran through several user stories and described the "plumbing", how the external events related to the application code, and how it worked with the kernel code. You could call it a "design document" if you want, but the real point of the exercise was to get some feedback from other engineers, as well as maybe getting my thinking a little clearer.
Another document, on the same project, was to explain what the above code was for and how it worked. I knew I was going away in a few weeks; furthermore, I was pretty certain that no one was going is going to touch that code for months. They needed some understanding of how it all related, so I sketch out a brief explanation of the algorithm (essentially, a combination of "requirements" and "design"), and then described how the components interacted. I wrote it as an HTML file, and saved it alongside some portion of the code it described (the old KeepDocumentationNearWhatItDescribes? rule) - probably the kernel code.
Mind you, the second document was written after the coding was essentially complete, as a note to the next poor sod who gets stuck with trying to understand the code. -- BillTrost
If instead of writing a text document describing the existing code, one writes a set of ProgrammerTests documenting the existing code, then one has a very beneficial artifact. The tests can be used to ensure one maintains the functionality of the code as it is reworked, and can be used by the "next poor sod" who needs to work on the code. It is simply much more powerful to create a set of tests that unambiguously validate correct operation than a textual description that provides limited guidance in validation.
Right. None of this addresses TheRoadNotTraveled, ThatsNotaBugItsaFeature, or any of the other myriad gotchas awaiting the poor sod who has to do maintenance on a piece of code that tells him nothing about why a particular choice was made. This has been hashed out at great length on other pages.
EditText of this page
(last edited November 12, 2005)
or FindPage with title or text search