Pixelate:Issue 11/Documenting Your Project
From Allegro Wiki
| Documenting Your Project (Part 1 - Overview) | |
| Original author: | Johan Henriksson (aka Mahogny) |
|---|---|
| Website: | |
| zip: | |
Most of us open source coders are really amateurs. This means that we learned how to code by ourselves. Sadly, this leaves a lot of holes in whatever knowledge a fully trained coder should have. In this series of articles, I will try to fill up what I consider the worst hole of them all; the ability to write documentation.
Every document has an audience. If it does not have an audience, it is pointless. So when we are writing something, we always have to ask ourselves, Who is gonna read this? There are generally three groups:
- The end-user
- Anyone who is gonna work on this project
- Yourself
Creating applications is an engineering task and, as in all engineering projects, information is more worth than the end-product in itself. The document is a tool on its own. We don't use the debugger for no reason and we don't document for no reason.
There are many questions to be answered here. What should we document? When should we document? And how should we document? In this first part I will show you the great picture and we will later delve deeper into the details.
As with any tool, there is no absolutely incorrect way of using it and documentation is by no means an exception. You will have to experiment by yourself and be ready to customize the process to better fit the project you are working with. What I present here is the method I have been using for my past projects. It is quite close to the method mechanical engineers use except it is much more suited for programming instead of construction.
Documentation is a continous process, although there are what I consider three stages in it:
- Before you code
- While you code
- After you have coded
Somewhere in here goes what everyone calls the design document. However, that is a word you will not see anymore because there is so much more to it than to just write a pile of papers and then get to work. You will always finish each stage before you move on to the next one, hence you should see that the process of documenting is tightly tied to that of the actual coding. Each step holds several questions that will prevent you from completing the next one and there is a high risk you will have to do extra work or get a bad solution if you start moving between the steps. This does not mean it will happen. You just have to be careful.
Before you start coding
To put this section in one sentence: Know what you are doing. That said, what does it mean in practice?
Libraries should not be overlooked. Decide already now which libraries to use and then read their documentation. What implications does the choice of each library have? Usually this affects the datastructures but it also tells if you need further encapsulation, what data the functions has to deal with and so on. This is common knowledge but by far too many times do I see coders decide on libraries all too late.
What data do you need to store? Libraries will decide on this but also how you are going to use the data. You also have to determine how you are going to use inheritance (this makes sense also for C programmers; the real question is, How to maximize code reuse?).
How do you store the data? This question goes hand in hand with what data you are going to store. However, there is much more to be said about storage. Is it faster to use a linked list, an array or a hash? This is not a guessing game. There are always ways to calculate this. This is however left for some other article.
The most overlooked part is the need for proper diagrams of dataflow. The key to finding bugs in an easy way (and not adding them in the first place) is to code according to a dataflow diagram in a structured manner.
Last, there is the question if the specification is reasonable. Make computations of memory usage, count operations that has to be done (computational complexity is always a nice starting point ??" if you have never read about algorithms, this is a good time to start). It should at this point be fairly easy to see if the project is realizable or not.
Many of these questions are however impossible to answer right away. The first part of documenting is to recursively nail down these questions by answering follow up questions. What questions to answer are project specific. One can however distinguish between two major groups; games and programs. There is much to be said about the follow up questions. They together form what most authors call the design document.
While you are coding
At this time, you are ready to fill in the details. The documentation you create here will serve as a help for you and the other team members. It will be of little interest to the end user. The most proffesional thing is to make it a separate document. This is however overkill for us amateurs. If the code is good enough, it will however serve as a documentation almost by itself though. This requires the code to be well documented and the names should help the reader. C++ coders have it fairly easy here, C coders has to a bit more careful. There are some things that goes outside the code however.
If someone who has no clue about the project wants to modify the code, it is not very nice if they have to open up the first file they find and then make their way from there. There are much better ways. If the code is well split into files, it will suffice to, in your dataflow/API diagram, point out which file holds which code. Another technique that works if there are not all to many files is to add headlines into the code that tells what the thing is about.
There should be a good buglist maintained. Store all symptomes and debug data in good place. This makes it easier to work in teams and, if the bug is so nasty it just will have to wait, you will be sure not to forget about it. When the bug has been fixed, it is a good thing to also describe the fix. By doing this, you will learn from it and hopefully you won't add the bug to some other code ??" or least you will know how to fix it.
Documenting changes is a good thing. If for some reason you find a bug, you can check the change log to see what might have caused it.
For you who, like me, have a bad memory, a short period todo can come in handy in case you of some reason have to stop working right in the middle.
As you can see, the documentation you write while you work is only supportative. The real planning was done before we even started with the coding. As I said, good code documents itself and if the planning was done properly, all this documenting follows naturally and is an integrated part of the development process, as it should be.
When you are done coding
This is (sadly) the well-known part of documenting. All the documentation you produce at this point is for the end-user. Depending on if it is a game, a library or a program, different approaches are taken. Just looking at some other game/program will give you an idea what you should put in. A mail adress or site so that the user knows where questions should go is the only thing I consider compulsory, otherwise it is an open question what should go in.
With this the first article has come to an end.
