===============================
Part II: Recommended UDF Format
===============================
This part will illustrate a standardized UDF format based on best practices collected from different UDF authors. It gives a good introduction in how to write a UDF that is easy to understand, portable, and emulates native KiXtart functionality pretty well.
The following recommended UDF format is based on the most restrictive settings in KiXtart in order to make the UDF as universal as possible. End-users should not have to worry about their script settings in order to run this UDF. The most restrictive settings are

Code:

SETOPTION('Explicit','On')

SETOPTION('NoVarsInStrings','On')

SETOPTION('CaseSensitivity','On')


EXPLICIT: This option requires to DIM all variables used in your UDF, they will thus not conflict with any variable of the same name that has been created outside the UDF.
NOVARSINSTRINGS: This option requires to not use variables within string delimiters.
CASESENSITIVITY: This option requires to compare strings by explicitly converting them to LCASE or UCASE if you do not want case sensitivity to be a deciding factor


Input Variables Your code should also check input variables for correct format and content. This will ensure that only correct paarameters are used iside your code. Incorrect values might have unexpected side-effects.
Error Codes When exiting a function in case of errrors, set an appropriate error code with EXIT. Windows error codes can be found under Microsoft Windows SDK: System Error Codes.
The Header
Fill out all header sections with meaningful and explanatory content. This makes it easier for KiXtart novices to understand the UDF and what parameters it needs to accomplish it's function.

Dependencies
A UDF does not need to check for the existance of its dependencies. However, dependencies must be noted in the UDF header. Also, the UDF does not need to check for the correct KiXtart version. Missing dependencies and incorrect KiXtart versions will already lead to error messages on the command prompt when running the script.

External Utilities
If a UDF is dependent on the presence of other components that might not be present o a computer, then this should be noted in either the DEPENDENCIES or REMARKS section, but preferably the first one. Third-party utilities should be referenced including a source where it is available. For example, Windows 9x/NT do not necessarily have the Windows Management Interface (WMI) or the Active Directory Service Interface (ADSI) installed. Thus you will note the dependency on WMI and preferable reference a URL where to download the WMI component.

In general, KiXtart UDF strive to emulate the format of native KiXtart functions, both in functionality (e.g. setting of error codes) and documentation. This ensures consistency across different UDF writes with their diverse backgrounds.

At first, all these guidelines and best practices might seem like overkill to you. However, the UDF Library so far contains over 300 UDF and it is still growing. Extensive documentation also makes it easier to maintain UDFs across different releses of KiXtart.


Edited by kdyer (2004-02-09 04:59 PM)
_________________________
There are two types of vessels, submarines and targets.