Hi, all ...
Documenting my sources is a very important thing for me, and it comes to be even more important when playing with big projects... however - and despite i found some marvelous tools such as doxygen - when it comes to titan work like Clicker (or any pretty advanced OS kernel), i can't keep the global picture ...
there are components, APIs, complex dependencies relationships ... i could write UML diagrams for all of these but then i would be stuck with documenting for about 3 years (aarg ... three years without coding, better not think about it :-p)
do you have any clue, tool, experience to share ? what is your policy about documenting ? or about group management ? ...
thanks in advance ...
Documenting your work ...
-
Pype.Clicker
- Member
- Posts: 5964
- Joined: Wed Oct 18, 2006 2:31 am
- Location: In a galaxy, far, far away
- Contact:
-
Tim
Re:Documenting your work ...
I can sympathise with you here since I am having a similar problem with the Mobius documentation. Doxygen is very good for small libraries or APIs where you want to document a set of functions automatically; however, it becomes unmanageable for large systems with lots of inter-related (or, more often, unrelated) components.
I'd like to end up with something like MSDN (http://msdn.microsoft.com/library/): a huge database of articles with extensive cross-referencing, and with minimal maintenance. So far I've managed to put together a repository of XML pages on MySQL. I tried a Wiki for a while, but I wanted something more structured.
What I've got so far is at:
http://www.themobius.co.uk/documentation/
I'd like to end up with something like MSDN (http://msdn.microsoft.com/library/): a huge database of articles with extensive cross-referencing, and with minimal maintenance. So far I've managed to put together a repository of XML pages on MySQL. I tried a Wiki for a while, but I wanted something more structured.
What I've got so far is at:
http://www.themobius.co.uk/documentation/
-
Curufir
Re:Documenting your work ...
Most of us (I absolutely put myself in this category) aren't as far along with our OS as you guys are. I do have a couple of general pointers that other people might find handy though.
1) Comment your sources. Despite rumours to the contrary there is no such thing as too much commentary in your source so long as it doesn't interfere with reading the code itself. If the only way you feel comfortable reading back through your source is to have every line of complicated functions commented on what you were doing/thinking/hoping to achieve then do it. One of the more distressing habits the vast majority of programmers slip into now and again is to stop commenting when they're working on a very difficult problem using the code/run/debug cycle. We've all been there, no doubt we'll all return there sometime in the future, but try to avoid it. There's nothing worse than looking back at your code after 3 or 4 hours hacking and realising you don't understand what the heck you did to get it working (Except perhaps not getting it working in the first place
).
2) If you're working on something difficult and are having problems debugging your code then do not simply delete the methods that don't work. Comment the non-working versions out to help you stop making the same mistakes over and over again. Delete them once the problem is solved and consider making a longer comment about why it was so difficult as a reminder when you read back through.
3) Comments are not just there for you (Although on this board that statement isn't as globally true). Make them concise, make them meaningful, and for godsakes make them understandable by a normal human being. If in doubt word your comments to be understood by someone who has no understanding of the rest of your code, and is just reading the function the comment is about.
4) When working on a large object/program consider having something like notepad open as well to make longer comments, rough design notes etc. Keeping a scratchpad like this for each of your individual programs as you write them makes it much easier to compose the real documentation later. It also often assists the design process to write things down instead of working from memory all the time.
5) If you're working in a group make sure only one person has the responsibility for documentation. This doesn't mean that only one person writes the documentation, it means that only one person is responsible for making sure the documentation is a) Written b) Legible c) Available to the group. If it is truly a very large project then consider splitting it between more than one, but make sure their areas of responsibility are clearly defined.
6) For published documentation there is no real excuse not to use a hyper-linked format. Being able to swiftly cross-reference information is an invaluable asset to a programmer. For a good example look at HelpPC, for a bad example look at man pages under *nix.
7) INDEXES. You could have the finest documentation in the world, but it's not going to do anybody any good if they don't know it's there. Have a defined starting point for the documentation, from which all documentation is available. Also useful is an alphabetical index of every documentation topic available. The idea here is to make it as easy as possible to find what you want, remember that sooner or later you'll want to use this documentation too so make it good. For a good basic example see the NASM html docs.
Keep it short, keep it simple, keep it targetted at specific areas. A 5000 word ramble on every function in a kernel is not as useful as splitting it up into different pages for different areas of functionality eg IPC, drivers, scheduling etc. Remember that large quantities of text are much harder to read/absorb on a computer screen than smaller quantities spread over more pages.
9) Keep your documentation synched with your programs. If your kernel is at v1.5 and the documentation is at v1.1 then your programmers are going to start and get mistrusting about the information the docs contain. If nothing about the API/Implentation has changed then at least update the version numbers.
Those are just some general points, hopefully useful ones. The subject of good documenation is a fairly lengthy (And often subjective) one. Fortunately the net provides some useful resources if you want to find out more.
1) Comment your sources. Despite rumours to the contrary there is no such thing as too much commentary in your source so long as it doesn't interfere with reading the code itself. If the only way you feel comfortable reading back through your source is to have every line of complicated functions commented on what you were doing/thinking/hoping to achieve then do it. One of the more distressing habits the vast majority of programmers slip into now and again is to stop commenting when they're working on a very difficult problem using the code/run/debug cycle. We've all been there, no doubt we'll all return there sometime in the future, but try to avoid it. There's nothing worse than looking back at your code after 3 or 4 hours hacking and realising you don't understand what the heck you did to get it working (Except perhaps not getting it working in the first place
).2) If you're working on something difficult and are having problems debugging your code then do not simply delete the methods that don't work. Comment the non-working versions out to help you stop making the same mistakes over and over again. Delete them once the problem is solved and consider making a longer comment about why it was so difficult as a reminder when you read back through.
3) Comments are not just there for you (Although on this board that statement isn't as globally true). Make them concise, make them meaningful, and for godsakes make them understandable by a normal human being. If in doubt word your comments to be understood by someone who has no understanding of the rest of your code, and is just reading the function the comment is about.
4) When working on a large object/program consider having something like notepad open as well to make longer comments, rough design notes etc. Keeping a scratchpad like this for each of your individual programs as you write them makes it much easier to compose the real documentation later. It also often assists the design process to write things down instead of working from memory all the time.
5) If you're working in a group make sure only one person has the responsibility for documentation. This doesn't mean that only one person writes the documentation, it means that only one person is responsible for making sure the documentation is a) Written b) Legible c) Available to the group. If it is truly a very large project then consider splitting it between more than one, but make sure their areas of responsibility are clearly defined.
6) For published documentation there is no real excuse not to use a hyper-linked format. Being able to swiftly cross-reference information is an invaluable asset to a programmer. For a good example look at HelpPC, for a bad example look at man pages under *nix.
7) INDEXES. You could have the finest documentation in the world, but it's not going to do anybody any good if they don't know it's there. Have a defined starting point for the documentation, from which all documentation is available. Also useful is an alphabetical index of every documentation topic available. The idea here is to make it as easy as possible to find what you want, remember that sooner or later you'll want to use this documentation too so make it good. For a good basic example see the NASM html docs.
Keep it short, keep it simple, keep it targetted at specific areas. A 5000 word ramble on every function in a kernel is not as useful as splitting it up into different pages for different areas of functionality eg IPC, drivers, scheduling etc. Remember that large quantities of text are much harder to read/absorb on a computer screen than smaller quantities spread over more pages.9) Keep your documentation synched with your programs. If your kernel is at v1.5 and the documentation is at v1.1 then your programmers are going to start and get mistrusting about the information the docs contain. If nothing about the API/Implentation has changed then at least update the version numbers.
Those are just some general points, hopefully useful ones. The subject of good documenation is a fairly lengthy (And often subjective) one. Fortunately the net provides some useful resources if you want to find out more.