[SugarfreeSA]

I believe that documenting anything with comments (be it code or a PostgreSQL database) should only be done for more complex pieces of code or to elaborate on something that could be misinterpreted.

Misguiding or incorrect comments caused by "Comment Rot" will actually cause more harm than having no comments at all. In fact, your code should be self explanatory (if you do it correctly) in terms of what it is doing. Adding extra comments to elaborate on "why" something is being done may be more useful - i.e. When the semantics of the code are not as easily deduced from the syntax.

For more information on "Comment Rot": http://blogs.msdn.com/b/ericlippert/archive/2004/05/04/12589...

However, I do find documenting database tables interesting and will consider doing it in the future under very specific circumstances. Thanks for sharing!

[eitally]

I've worked intensively on a schema (as an end user developing reports against it) where several columns in one of the tables were flex fields whose content/use changed dependent on a different column's value. It was always a bear to train new developers on it and it wasn't documented anywhere (until I created a flat file documenting it). In a situation like that I'd have loved inline tabular comments.

Similarly, if a table or a field has become "legacy", that is, no longer actively used but kept around because there's old data in it somewhere, that should be commented, too. Or, if a column has it's datatype changed for some reason while there is data in the table, that should probably be noted, too (e.g. char --> varchar, int-->string, etc).

Schema versioning is a huge problem at many companies, especially non-tech companies where the developers are completely at the mercy of their "business stakeholders", and since full-fledged data dictionaries don't exist for almost anything, using simple comments like this could be a boon. I dunno, ymmv, but I'd have appreciated it.

[SugarfreeSA]

Yes, I definitely see value of comments in a situation like flex fields because that's something that may not be straight forward or clearly apparent!

Legacy tables or fields also make sense because the code will remain the same and thus lead to no comment rot.

As long as the comments stay relevant and cause no extra confusion, then it is useful! I suppose it is also situation dependant as well as the preference of the development team at the time.

[cmdkeen]

I agree that normally code should be clear and obvious and require little in the way of comments. The difference is that tables aren't code.

I work with a large Oracle DB which has a mixed attitude towards column comments. You don't have many characters to semantically name a column. If you're using table per hierarchy, or denormalised conventions then it can be entirely unclear which columns are supposed to be used for each row types.

Comment rot is a useful thing when it highlights that something is wrong - e.g. a new value in a table commented as accepting "Y" or "N", which prompts you to go an examine code elsewhere to find out what is going on.

My current thoughts are that all table and columns should have at least some form of comment.