Posted by J.O. Aho on 11/10/06 11:01

sTony wrote:
> I must point out
> that the website I'm building is meant to be polymorphic, and it is being
> designed to grow in unforseen directions. In order to accomodate this
> growth, there does needs to be solid documentation, so as to cut down on
> design errors, which there will also undoubtably be, and also to promote
> understanding of what the table is, and what its reason for being is. The
> reason for the seperation of the files is so that people can edit/add the
> tables needed for the websites expansion and improvement, without having to
> sort through or understand all of the tables of the website. Knowing this,
> do you still think its a mistake to put the comments in the database
> definition files? I really want your opinion. The database aspects are
> giving me more troubles than anything else. It just seems so foreign to me
> still, and I expect that a guru could easily find more than one problem with
> my databases structure. Anyhow, I appreciate the advice, and I'm eager for
> more.

There are two schools when it comes to comments, one that thinks you don't
need those and the other where comments are used to describe what is been
done, of course the comments don't replace proper documentation.

The gain you get without comments are smaller source files.

the gains you get with comments are easier to understand sources (if the
comments are describing).

Of course all to much comments will lead to a big and difficult to follow
source, so you need to balance things a bit to really get a good source.


For those who does think comments shouldn't be used, then please make a big
procedure with usage of functions with not that logical variables, put it away
and take a look in five years time and tell what you thought when you made that.


//Aho

[Back to original message]