It seems everyones has their own experiences and horror stories. One year a go I joined a company where all the previous developers had walked out in one day. The was no documentation (they never prepared it) and no user manuals. Talk about a struggle.

Some form of documentation is needed to understand the business logic that is being implimented.  I tell my team that I'm not planning on leaving soon but I could be hit by a bus crossing the street tonight.

All new development include header comments on who coded the program unit, when it was done, and why it was done. I go a step further and include comments on the arguments, the result set, any return values, as well as constants or configuration values that need to be set. I do this because it make it very easy to share documentation with consultants who are preparing external services for us.

The most critical comments though, are the comments documenting changes.

In the header we include the following:

--  MODIFICATION HISTORY

--  --------------------

--  DEVELOPER:  R. B. Morrison

--  DATE:       June 13, 2006

--  REF:        20060613

--  COMMENTS:   Modififed search criteria to remove the date added and

--              include date modified.

Within the code the following comments are made:

SELECT  first_name

      , last_name

      , address

      , city

      , state

--  START   20060613

--      , date_added

      , date_modified

--  END     20060613

FROM    members

Now when we need to find the changes that were made, we use the search tools of Query Analyzer (or what ever tool we are using) to find where the reference number occurs.