I have released a new OSS project called DataModels (this should be especially interesting if you use DataBlock). It is basically an effort aimed at reusing  specific data models.

The project's page is here.

 

So, first of all, how would a GOOD documentation would  help us ? What would we gain from it ? Well :

- new people could be brought to speed very easely. No need to chaperon them while they understand the system, no need for different programmers to each explain to the new guy a small piece of the system.

- easy maintainance.

- remove dependency from the people who designed/understand the system.

 

Here's my take on what and how this should be done.

- document the initial requirements of the project.

- the "core" of a business system is the database schema . That's the most important thing which should be documented.  SqlDoc is a great tool for this. If you can't afford it then use a simple text editor. But DO document the schema of the database.

- document all the business procedures and requirements of the system. Some businesses have some pretty wacky procedures and requirements (if you worked with a financial system for instance, you probably already know that). Gather all these procedures and requirements and document them. Make sure the documentation is "tied" to the documentation of the database schema.

- create a entity relationship diagram.

- the most important advice of all : be explicit. Do not use shortcuts in the name of the database columns and do explain the specific business terms.

 

Funny thing....the intro movie from The Witcher is actually based on the first chapter of the book. Good stuff. The book is composed of a few short stories interwoven together. It's okeish but nothing great. I hope the saga will be better  (although it will take some years until it will be translated in english....the second book in the serie was written in 1995 and it will be released in english in 2010).

 

 

My thoughts about code comments :

- code and API comments are 2 different things and should be treated differently. 

Code comments :

- most of the time "method" comments should NOT be necessary.  Code should be written using guidelines that specify long and meaningfull names to all types. Hence if the method is called GetAvailableUsers then what's the point in adding a comment like "Gets the available users"?  The method name already tells the person who's reading the code what is does.

- comments should ONLY explain the WHY (why is the code doing this thing in this way ?). We can find the HOW just by reading the code.

- comments should be added only when there is need for them. There is no point in commenting everything (most people hate "green noise" when they read code).

- some people use comments hoping to "fix" badly written/broken code. This is SOOO wrong.  Documenting a mistake will not make it better. Consider refactoring the code and removing the comment.

- comment rot is very bad. When you refactor a piece of code, DO remove the unnecessary  comments.

- do NOT create a file header (with the name of the person who created the file, creation date etc etc). These stuff can be easely inferred from source control.  

API Comments :

- code samples are much more important than comments.  It's much more simple for the API user to have a sample on how to achieve a certain thing then to try figuring for himself by reading the API comments.

Interesting documentary about the first days of the Mozilla project.

Few things jumped (back) to mind :

- Microsoft was beeing sued for making a free product. Oh...the irony.

- Netscape Navigator was pretty crappy compared to IE (4). Using IE4 in Win98 was a MUCH better experience than using Netscape.

- try to imagine the browser landscape today if Ms wouldn't have abbandoned IE after winning the Netscape battle.

- kind of ironic to see that a corporation opened the code to save itself, failed to do so (AOL buy Netscape sealed the deal) but , years later, there is a company which makes money from Netscape's code (yeah..i know....most of the code is rewritten but you get the point).

It's a pretty good reference book. Sometime it feels like it rehashes POEAA but overall the content is ok. The only exception is the Data Access chapter which could have simply been replaced with "Use a ORM".