Usage Guidelines

SQLHelp, like any other developer tool, is capable of considerably more than first glance would indicate.  Here we present several hints to derive the most from SQLHelp.  

Define the SQL Interfaces Early

Using the ##OV tag the intent behind the stored procedure can be defined before a single line of SQL is ever written.  

Optionally, project global overrides van be defined in the user interface.

Remove ##OV as Procedures are Completed

As valuable as the ##OV is during interface design, it can be a hindrance to ensuring the procedures are correctly documented.  Since ##OV actually prevents the SQL parser from parsing the batch, if there is a departure from the design, SQLHelp will not be able to locate it.

Optionally, the ##NOV tag can be used to remove the overrides on a per procedure basis.

Run SQLHelp Frequently 

Running SQLHelp periodically as projects progress can highlight potential bugs before they manifest themselves.  SQLHelp does this by noting those parameters that are not yet documented.  If a parameter or column alias is not yet documented, this could indicate a departure from the original design, and likely indicates a situation where code has been developed that is potentially no longer in spec.

Provide Rich Descriptions

Since you never know who might need to use the interfaces being developed, or how far in the future this need might arise, the richer the documentation you provide, the greater the likelihood that ongoing maintenance will be successful.

Document each result set returned

If returning more than one result set, documenting each one independently allows the users of the documentation to better understand each result sets purpose. 

 

© 2001-2004 Pikauba Software. All rights reserved.