Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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

share|improve this question
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
7  
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
6  
@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 ;). –  Martin Blore Mar 17 '11 at 19:48
show 8 more comments

9 Answers

up vote 2 down vote accepted

Yes.

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.

share|improve this answer
8  
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
1  
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. –  Dr. Zim Mar 17 '11 at 23:27
3  
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. –  Evan Plaice Mar 18 '11 at 11:54
show 1 more comment

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.

share|improve this answer
2  
+1 for TDD. Absolutely a better option than documenting, then having to change significant amounts of documentation if the code changes. –  Ethel Evans Mar 17 '11 at 21:45
    
Also +1 for documentation in the form of TDD. –  sevenseacat 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. –  Evan Plaice 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). –  Evan Plaice Mar 18 '11 at 12:06
show 2 more comments

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.

share|improve this answer
    
Exactly! Change happens. Documentation rots. Code is the truest form of documentation. –  Dr. Zim Mar 17 '11 at 23:21
add comment

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.

share|improve this answer
add comment

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

share|improve this answer
add comment

Joshua Bloch discusses this very point in his interview for the book "Coders at Work". He is a truly intelligent person and I always find him very enlightening.

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.

I know that he addresses this point but unfortunately I can't remember exactly the way he puts it, so it'll be better if you can get a hold of the book and read the whole interview. As I said, he is always very enlightening.

share|improve this answer
add comment

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
share|improve this answer
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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