Andrew Fraser DBA

Documentation and Comments

Steve Feuerstein here:

There are two forms of code documentation: external and internal. External documentation is descriptive information about a program which is written and stored separately from the program itself. Internal documentation, also known as inline documentation or comments, is placed within the program itself, either at the program level or the statement level.
The best kind of internal documentation derives from your programming style. If you apply [my] guidelines, you will be able to write code which is, to a great extent, self-documenting.

Best practice for documentation is:

1. Write code in a style that is self-documenting.
2. To the extent that is not possible, then keep the documentation internal to the program itself, in the form of comments.
3. Only if that is also not possible, should you resort to external documentation. In that case keep the external documentation easily accessible by URL and state that URL inside the program comments (and/or display in the application front end).

Ideally, the only external documentation needed is the high level overview containing just:

1. Server name(s)
2. Database name(s)
3. Owner username(s)
4. Details of where to find password(s) – e.g. full path details of a KeePass encrypted file.
5. Any helpful visio-style diagrams

The most important set of comments is this initial set – and this should appear in every piece of code you write:

CREATE OR REPLACE PROCEDURE myowner.myprocedure AS
/***************************
|| Name : 
|| Author : 
|| Date : 
|| Purpose : 
|| Change History :
||     date author refno description
***************************/

Of those fields, author is the most important.

Counter-intuitively, simple short programs actually need that header info more than long programs – because you can more often work out the purpose of long programs by reading through their code.

Focus on the why, not the what.

Packages should have these comments in the package body, not the package header, because the body is more often modified and contains the most code.

Views need commented just as much as pl/sql. But their comments need to go after the select keyword:

create or replace [materialized] view myowner.myview as select
/***************************
|| Name :
|| Author :
|| Date :
|| Purpose :
|| Change History :
***************************/

Triggers and functions also should be commented with the some format. As should any SQL script files and shell script files.

For SQL script files, set doc off first to avoid having the comments echoed out to screen every time the script is run:

set doc off
/***************************
|| Name :

Shell scripts should follow the same comment format as sql, except for ‘#’ symbols:

##############################
# Name :
# Author :
# Date :
# Purpose :
# Change History : 
##############################

PHP files also should have the same initial comment block, except marking lines with * is more standard for php:

/***************************
* Name :
* Author :
* Date :
* Purpose :
* Change History :
***************************/

Windows .bat command scripts use rem, and also need ‘@echo off’ at the start in order to suppress echoing out the comments every time they are executed:

@echo off
rem Name :
rem Author :
rem Date :
rem Purpose :
rem Change History :

Functions and subroutines, whether in php, shell, or pl/sql package bodies, should each get their own introductory comment block – although without the change history, because that is best maintained in the overall initial comment block.

Oracle Forms screens should all have that same initial comment block placed in their when-new-form-instance trigger. If necessary, add the when-new-form-instance trigger purely to contain that comment block. And again each program unit within the form would also get its own introductory comment block.