These are some comments from my source code, I thought they were 'fun' so I thought I'd share them here:
/*======================================================================*\
*
* A NOTE ON NULL:
* ===============
*
* JE 2003-10-10 1726:
*
\*======================================================================*/
/*
*
* NOTE: these are the definitions of null as used in these comments.
* CASE IS IMPORTANT!
*
* null: a null reference as per the framework.
* NULL: a NULL value as per a database.
* DBNull: a representation of a NULL value for the framework.
* PK: stands for Primary Key, used to uniquely identify an Entity
* FK: stands for Foreign Key, used to uniquely identify a related Entity.
* indeterminate: is not meant to have the same meaning as NULL. in this
* context it means that the value can not yet be known, but will
* ultimately be a non NULL value.
*
* DBNull is an abbreviation of DBNull.Value.
* DBNull does not equal null.
* DBNull implies NULL.
* null implies indeterminate value, and is only used for Key objects
* (i.e. PK's or FK's) when the Key is not NULL but rather indeterminate.
* The reason a Key would be indeterminate is that the Entity that the
* Key would identify has not yet been persisted to the database and has
* therefore not yet received an ID.
*
* if the foreign key is null then it is an indeterminate key, but
* not a NULL key.
* if the foreign key is DBNull then it is a NULL key.
* in any other case, the key is not NULL and will be of the
* corresponding framework type for the database type, typically int,
* possibly string, Guid, etc. so all we need to do is check if the
* foreign key equals DBNull to determine if the key is NULL. A foreign
* key can be indeterminate when an object has been locally allocated
* as related via that property, but since it is new it has not yet been
* saved to the database. This is not an error, and is not the same as
* the FK being NULL. In this case the FK will be known after the related
* entity has been persisted to the database and a key has been allocated.
*
*/
Does that sound fair enough to everyone else? :)
I just thought of a cool feature for Visual Studio. It'd be nice if there was a spell checker that operated on string literals and comment sections, that automatically included any local variable or class names (as per Intellisense) in the vocabulary.. compiler warnings from the spell checker would be a bit much though! ;)
John.