Meta Commands

[RhoSigma]

Here's the transscript from the conclusion of a discussion we had with Steve, Terry and others a couple years ago on the old forum regarding the requirements for proper "Library authoring":

Steve:
    1) Subs/Functions should start with creator initial.  A Steve(tm)
library would use SM_ for naming convention.  Sure, there might
be more than one guy with the SM initials out there, but if there
is, he hasn't posted much here on the forums, and all conflicts
with SM_Xpos and TR_Xpos are instantly cleared up...
RhoSigma:
Although I mentioned this kind of ID earlier too here in this topic,
after rethinking I came to the conclusion that we don't necessarily
need IDs for SUB/FUNC names. Why?? - Every library has a specific
purpose, eg. imageprocessing, spritesheets, menu, database, sorting
etc., from that point of view the SUB/FUNC names should be unique
enough between the different library types, as the names are usually
chosen having the context of the respective library in mind. Even if
there may exist more than one library for the same purpose, eg. three
different spritesheet libs from three different authors, then still
the user will most probably decide to use just one of it, the one
which fits best for his needs.

Steve:
    2) GLOBAL Names should be self descriptive as much as possible.
SM_TextToImage is much easier to understand, remember, and use
than SM_TTI, and chances are, it's also more resistant against
accidental duplication.
RhoSigma:
Agreed, however for me it doesn't matter if the initials are
representing the authors name or the library name/type. Every author
should just be consistent on his preferred naming scheme.

Steve:
    3) COMMON variable names (such as any single digit character)
should *always* be LOCAL and TEMPORARY in scope.  Don't DIM
SHARED X, Y, I, K, M, ect...  Keep them reserved as temp
variables and they should never interfere with another user's
variables.
RhoSigma:
Totally agreed.

Steve:
    4) Unless NECESSARY, Subs/Functions should never pass values back
via the parameter.  Instead of SUB SM_MathJunk (X, Y), values
should be passed as SUB SM_MathJunk (TempX, TempY), with the next
line reading X = TempX: Y = TempY.  This practice prevents all
instances of accidental value corruption.
RhoSigma:
Agreed, however it seems you chose the easy way for you as library
implementor. I personally would leave it as SUB SM_MathJunk (X, Y)
for the public user and rather do tmpX = X: tmpY = Y internally, as
any unexperienced user could be confused, if he reads to give
"temporary" arguments to a SUB/FUNC call.
  Very important, if argument side effects are necessary/intended,
then this MUST be explicitly mentioned in the respective function
description. Also remind the potential user of such a SUB/FUNC that
he should not use extra parenthesis to make a BYVAL parameter
transfer. Also he can not give any literal values, but only
variables of the very same variable type as specified in the
parameter list, because QB64 would internally create a temporary
parameter for literals or wrong variable types, which would
compromise the intended side effect.

Steve:
    5) Arrays should be hard indexed.  Don't DIM SHARED Array(10);
instead DIM SHARED Array(0 To 10).  This prevents incompatibility
if the user has OPTION BASE 1 in effect.
RhoSigma:
Indeed, I've never thought about this one Steve, agreed.

Steve:
    6) Subs/Functions should *always* restore settings before exit.
If your sub needs a _DISPLAY to show text on the screen (such as
for a message box), check to see if the user had _AUTODISPLAY on,
and if so, restore it on exit.  _DEST, _SOURCE, _BLEND, COLOR,
Visible Screen, and lots more *can* be altered while in a sub,
but unless that's the intended purpose of the sub, it shouldn't
happen in Library code.
RhoSigma:
Totally agreed.

Steve:
    7) Useage of Global Flags/Metacommands should be avoided.  DON'T
count on DEFLNG A-Z to be set, or OPTION BASE to be 0/1, or
$DYNAMIC to be in use.  Once you share a library publicly, you'll
run into somebody who has the option set completely backwards of
what you always ASSUMED was standard.
RhoSigma:
Indeed, never count on it and never ever even think on defining it in
your library. Also, just as Terry mentioned, don't ever think on
defining CONSTs for true/false, consider it would be the same as
doing a DEFLNG A-Z in your library. Instead use type suffixes in your
library code and literal booleans 0/-1 as suggested by Terry.

I used this to condense it into some simple rules I follow in all my libraries (see links in my signature) to make them as compatible as possible. These rules are as follows (note the numbers in () which coresspond to the sections in the quote above):

- Make a section in the beginning of each SUB/FUNC where you DIM all variables (OPTION _EXPLICIT requirements), even if you usually code without it.

- (7) Use variables with type suffix & literal bools 0/-1, don't assume or set defaults such as DEFINT etc. or constants like TRUE/FALSE.

- (2) Use descriptive global variable names with prefix (in CONST, DATA, (RE)DIM/COMMON SHARED etc.).
- (5) Always hard index global/local arrays (eg. (RE)DIM arr(0 TO 10)).
- (1) Sub/Function names doesn't need prefixes but names must be clear in the library's context.

- (4) Avoid argument side effects (use temp vars), but mention it explicitly in the docs if those are intended for some reason.
- (3) Keep ordinary 1-2 letter variables temp/local to SUB/FUNC, see also (2).
- (6) Restore changed modes (_SOURCE, _DEST, _PRINTMODE etc.) before exit/end SUB/FUNC.