I removed the personal comments, refined the language a little, and added Shawn's comments. If this meets general approval, maybe it can go in the FAQ area.

KiXtart UDF "Ten Suggestions"

1. A function should be pretty much unbreakable. It should prevent or gracefully handle internal errors to the greatest extent possible. An end user should never have to waste their time troubleshooting a poorly written UDF.

2. A function should still return a value of the type expected even if it cannot finish normally -- thus helping prevent type mismatches -- but the value should be zero, empty, or null. If the values supplied should never be zero, empty, or null (i.e. MyBodyTempNowCelcius() should never return a zero under normal circumstances), the data itself can act as the error. Otherwise, the function should set an error number on exit for testing from the calling script.

3. A function should be independent. All internal variables should be declared to prevent confusion / conflict with global variables. (Variables in function arguments are automatically dimensioned by KiXtart.)

4. Global resources should be used with great caution. KiXtart settings changed within the function need to be reset to their previous state before exiting the function. Files opened by a function should be opened in a way that they won't interfere with file numbers in the calling script. One possible way to handle (no pun intended) file numbers when using the KiXtart open() function is to reserve file numbers 1-5 for main script files handles and 10-6 for UDF file handles.

5. A function should return what the average user would intuitively expect. In other words, most numeric functions return a number. Most string functions return a string. There are obvious exceptions, of course. Instr() *should* return a number. But it would be odd if that function returned an array.

6. Try to make the arguments and return types of functions as intuitive as possible. Ideally, any end user should be able to copy a UDF into any script and expect it to work with no modifications and without having to dig into the code to figure out why it returns a value of more than one type or works right when MyFunc(10) is supplied, but breaks when MyFunc('10') is supplied.

7. UDF's should be well documented and tested. Known limitations of the function should be documented. For instance, it may be OK if a function like Divide(A,B) can not return a correct value when B=0, but this should be documented. A real plus is to include extensive testing code along with expected results so the end user can verify the results on their particular combination of HW/OS/KiX versions before implementing the function. Ideally, include abbreviated documentation within the function itself to briefly describe general syntax, expected arguments, returned value/type, error handling, and point of contact for questions/problems.

8. A function should be readable enough for the end user to customize it, if so desired. (This is strictly a personal preference. Most people probably only want to use a UDF, not tinker with it.)

9. Function names should be as intuitive as possible. ReadProfileString() or GetFileSize() is preferable to mydatnumfunc(). (Note the action-object-type structure of most function names.) If you are aware of another UDF with the name you prefer, be graceful and give yours a different name to avoid confusion. Be cautious with function names you anticipate may be added to KiXtart as internal functions supercede UDF functions of the same name.

10. The KiXtart community is highly libertarian in coding practices. The previous suggestions are just that -- suggestions. Please do not use these suggestions to harrass, indimidate, or bully anyone writing KiXtart code, no matter how bad that code is or how much it makes you whimper when trying to decipher it. Instead, encourage one another. Make suggestions (like these). Show someone a better or faster way to do something. We will all benefit.

finis

[ 24 April 2002, 16:36: Message edited by: New Mexico Mark ]