Has anyone ever tried creating a complete code documentation first, before actually writing the code? I was thinking about this earlier because I thought it would help to write a concrete interface and would make sure your initial design wasn't floored by making you think about how classes interact. Is this a good idea? Has anyone tried it? Ell

  • 2
    Yes. It's a good idea. People do it all the time. What more do you want to know?
    – S.Lott
    Mar 17 '11 at 19:29
  • 9
    This is a subjective question. Someone has done it at least some of the time, so the answer is bound to be yes. I personally prefer to just jump in and make a prototype first, as I will inevitable rediscover a better design about 5 times in the process. When tackling something complex, I scratch something on a piece of paper first. If it is trivial, then I tend to just jump right in. StyleCop helps me to fill the gaps later.
    – Job
    Mar 17 '11 at 19:32
  • 2
    It's a great idea, otherwise you end up with undocumented features.
    – chrisw
    Mar 17 '11 at 19:33
  • 8
    @S.Lott the simple fact that he's asking the question kind of implies he is looking for some more information as I'm pretty sure you were aware. But it seems like you prefer making snide comments about other peoples faults.
    – Kenneth
    Mar 17 '11 at 19:37
  • 2
    It would be even better if you wrote acceptance tests, and then used TDD to fulfil those Acceptance tests ;). Mar 17 '11 at 19:48


It gets you thinking about what, exactly, your code is supposed to do. The idea is that you could start with any part of the code and know exactly what needs to be done to complete that module.

It's also easier fix something on the drawing board than in the IDE.

  • 12
    Easier to fix, yes. Easier to notice, rarely. Designs almost always look good until you attempt to implement them.
    – CaffGeek
    Mar 17 '11 at 20:00
  • @Chad That's true. I've edited my answer to reflect that.
    – Maxpm
    Mar 17 '11 at 20:22
  • 4
    I disagree. Creating complete documentation first is far worse than just enough documentation to know where to go next. Change happens. There's no way to know if you are going in the right direction, and by the time you figure it out, you are way behind. Go with what works, improve and fix it as you go, let the code be the most up to date documentation. Mar 17 '11 at 23:27
  • 4
    Of course as soon as you change your code to fix a bug or to meet a new requirement, your documentation is out of date. Documentation as executable tests is the way to go!
    – Johnsyweb
    Mar 18 '11 at 3:41
  • Draw up (sketch/outline) ideas beforehand yes, but don't create documentation. Unless you prefer to waste a lot of effort because you'll be throwing away a lot of the initial effort as the design is put to practical application. Plus, only public or internal classes/methods should be fully documented (including full description as well as parameters). Private local stuff should have one-liners that describe what they do for future reference but anything more is a waste because they'll inevitably be skipped over during the documentation generation phase anyway. Mar 18 '11 at 11:54

There are two ways of thinking about it:

1) Documentation as in Word documents, Wiki, etc. By definition you cannot have a complete code documentation because you don't have a code to document. You can try to document hight level design, assumptions, interfaces and contracts first.

2) Documentation as executable tests. There is a school of thought that states that executable unit tests is the best documentation. This school of thought also advocates this kind of documentation before writing the code (TDD). At the same time you don't write all the tests for the whole system right form the start. You break it down by use cases first, then you do tests and code per use case.

  • 2
    +1 for TDD. Absolutely a better option than documenting, then having to change significant amounts of documentation if the code changes. Mar 17 '11 at 21:45
  • Also +1 for documentation in the form of TDD. Mar 17 '11 at 22:49
  • you CAN have complete product documentation before the product exists. I've done it, I've worked in projects where it was a requirement. You won't have screenshots, but you can have everything else (including Visio diagrams representing the location of elements on screen).
    – jwenting
    Mar 18 '11 at 7:45
  • @jwenting I have too and it was a collection of diagrams as well as 200+ pages of word documents. Not only was it a complete waste of time but it required 2 months to produce and a significant amount of our PMs time to constantly update as the design evolved into the final product. It actually probably would've gone a lot faster with graphical mockups using Balsalmiq. Next time I work on a project where this is a requirement I'm going to make a point that another person should be assigned to manage it full-time because that's how much effort it takes to maintain. Mar 18 '11 at 12:01
  • +1 TDD for basic proofs of individual components and diagrams for overall design assumptions (emphasis on assumption because the actual design should be written as the best practical application not as a 1-1 implementation of the diagram, they're called assumptions for a reason). Full software documentation of all public/internal classes/methods/properties comes last through a documentation generator (all properties/returns/remarks should be filled in first) and all private/local stuff gets one-liners to describe what they do for future reference (private/local is ignored by the generator). Mar 18 '11 at 12:06

Starting with the documentation is classic waterfall model, and has all the pitfalls associated with that model. Broadly, the more you document the more you have to update when the requirements change. One benefit of starting with user documentation is that you might get feedback (and hence changes) sooner. But experience shows that most people are bad at mentally mapping documentation to actions. So we use prototypes instead, which allow people to actually use the software and give feedback that way.

One variation on "documentation first" is literate programming. Start by writing a description of what the program will do from a programmers perspective. Keep tweaking that until it compiles. Voila, a literate program.

  • Exactly! Change happens. Documentation rots. Code is the truest form of documentation. Mar 17 '11 at 23:21

I personally find it better to use diagrams (such as UML) to do simple modeling to show the flow of things. This is much quicker than documenting things out in words and if done right can be just as descriptive. I would be hesitant to do Full Documentation though because personally I haven't ever had a project I've worked on that hasn't changed through the course of programming it.

EDIT: Some documentation though should be done as you go a long. This makes it easier to do the full documentation later.


Joshua Bloch discusses this very point in his interview for the book "Coders at Work".

Contrary to more orthodox and academic views, he advises something to the tune of your thoughts (maybe you have read it there yourself?): that before writing the documentation you have to understand what do you want from the system and get a more "real" feeling. For this purpose he would design part of the interfaces and some client code that uses them.

The most important thing is to know what you’re trying to build: what problem you’re trying to solve. The importance of requirements analysis can’t be overstated. There are people who think, “Oh, yeah, requirements analysis; you go to your customer, you say, ‘What do you need?’ He tells you, and you’re done.”

Nothing could be further from the truth. Not only is it a negotiation but it’s a process of understanding. Many customers won’t tell you a problem; they’ll tell you a solution. A customer might say, for instance, “I need you to add support for the following 17 attributes to this system. Then you have to ask, ‘Why? What are you going to do with the system? How do you expect it to evolve?’” And so on. You go back and forth until you figure out what all the customer really needs the software to do. These are the use cases.

Coming up with a good set of use cases is the most important thing you can do at this stage. Once you have that, you have a benchmark against which you can measure any possible solution. It’s OK if you spend a lot of time getting it reasonably close to right, because if you get it wrong, you’re already dead. The rest of the process will be an exercise in futility.

The worst thing that you can do—and I’ve seen this happen—is you get a bunch of smart guys into a room to work for six months and write a 247- page system specification before they really understand what it is they’re trying to build. Because after six months, they’ll have a very precisely specified system that may well be useless. And often they say, “We’ve invested so much in the spec that we have to build it.” So they build the useless system and it never gets used. And that’s horrible. If you don’t have use cases, you build the thing and then you try to do something very simple and you realize that, “Oh my gosh, doing something very simple like taking an XML document and printing it requires pages upon pages of boilerplate code.” And that’s a horrible thing.

-- Joshua Bloch, from an interview in "Coders at Work: Reflections on the Craft of Programming" by Peter Seibel

If you're already thinking along these lines, it'd be good if you can get a hold of the book and read the whole interview. As I said, he is always very enlightening.

  • This is good advice, but good documentation includes usage of the API. May 11 '18 at 0:01
  • For the record, while I appreciate the edit, I think that quote might not have been the one I was thinking about. It seems tangentially related and more high level or related to the requirements phase. I think he said that before writing documentation he would start coding, writing client code that would use the interface in order to have a rough idea of the right interface and that (this is the counter intuitive part in my opinion) that should come first, before writing any low level design doc at all. Of course it's my fault for not having found the quote when I wrote this answer.
    – DPM
    May 11 '18 at 0:15

Some people even go further and state that a company should completely work backwards, so

  1. Write the press release
  2. Write a FAQ
  3. Define the customer experience
  4. Write the User Manual
  5. Start programming

See http://www.allthingsdistributed.com/2006/11/working_backwards.html


Writing the complete code documentation first is probably overkill and somewhat reminiscent of the waterfall methodology. However, I've found that a more pragmatic approach is writing the README first. Here's why:

The README does not document every detail of your project. Instead, it typically contains the following info:

  1. Description: short "sales pitch". Tell the reader why they should keep reading.
  2. Quick examples: short code snippets or screenshots to support the description.
  3. Quick start: how to get going, install instructions, and more examples.
  4. Further documentation: links to the full docs and more info.
  5. Project organization: who are the authors, how to contribute, how to file bugs.
  6. Legal notices: license, copyright, and any other legal details.

Writing the "sales pitch" up front forces me to be crystal clear about why this project should exist and why developers should use it. The mere act of writing full sentences to describe the project often changes it for the better: you understand it better, develop new ideas, and uncover potential problems. It's also a great prioritization tool: anything in the "sales pitch" is a must-have!

The "quick examples" and "quick start guide" force me to think through the key use cases from the user's perspective. I've found that doing this before writing any code - before being bogged down in implementation details and tight deadlines - leads to much cleaner APIs and designs. Remember: programs should be written for people to read, and only incidentally for machines to execute (SICP).

In "further documentation", I create an outline of the pieces that will need detailed documentation, to be done later. "Project organization" lets me figure out who will work on the project and the coding practices. "Legal notices"... well, may as well get those out of the way too.

Once you have this basic README in place, you have a document that's useful for discussion, design reviews, dividing up the work, and project planning. As you work on the project, frequently check back with the README to make sure you're still on track. Also, incrementally updating the README and the "further documentation" as you go means all your documentation will be done when the code is done, which is a much more pleasant experience than having to rush through documenting everything last minute.

For more info, check out the following:

  1. Readme Driven Development
  2. The most important code isn't code
  3. You are what you document

Why wouldn't you want to think about how classes interact? Why is that a bad thing? I actually think about the interactions before I even know what the classes are. That way the classes identify themselves.


You should have some idea of what you plan to do before you write the code. The issue always is how do you keep what you've coded in synch with what you've written? Some say don't try, others say forget the initial docs and keep up the comments. Of course the code is always the canonical source. The issue then becomes whether it is worth the effort to document what the code does for those who come later or use the code. Anyone can figure out what a function does. The writer's job is to help someone understand in 5 minutes what anyone can figure out in an hour. Add up the deltas and determine your path.

Not the answer you're looking for? Browse other questions tagged or ask your own question.