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
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.
|
|
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. |
|||||||||||||||||||||
|
|
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. |
|||||||||||||||||||||
|
|
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. |
|||||
|
|
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. |
|||
|
|
|
Some people even go further and state that a company should completely work backwards, so
See http://www.allthingsdistributed.com/2006/11/working_backwards.html |
|||
|
|
|
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. |
|||
|
|
|
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:
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: |
|||
|
|
|
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. |
|||
|
|
