Historical CodingConvention, Revision 4
Trying to create something similar to this.
Variable names
All strings must be prefixed by a lowercase s, followed by first letter of every word in caps. Example:
sequence sMyString, sName
All integers must be prefixed by a lowercase i, followed by first letter of every word in caps. Example:
integer iAge
Exceptions when you don't need to prefix a variable name by i, are the following variable names: maxlen, i, j, k
All atoms must be prefixed by a lowercase a, followed by first letter of every word in caps. Example:
atom aYear
All booleans and flags (even if you're using an integer to identify 0/1 condition) must be prefixed by a lowercase b, followed by first letter of every word in caps. Example:
integer bFirstTime, bSeenBefore
All other variable names must be all lower case. Multiple words separated with an underscore. Example:
age = 25 customer_age = 31
Function Names
Function names must have first letter of every word in caps. Example:
function MyFunction(...)
Exceptions: System functions and runtime functions should remain all lowercase (i.e. strcmp, stripslashes)
Constants
Constant names should always be all caps. Example:
constant MAX_NUM_DAYS_IN_MONTH = 31
Indentation
Avoid using spaces for indentation. Start your code at the far left corner and use tabs for indentation. Example:
function MyFunction($variable) -- Do something puts(1,"Hello World") if (1 == 1) -- Do something else puts(1,"Goodbye") end if end function
When assigning values into multiple related variables, always left justify assignments. Example:
-- set post username/password input[1] = account_id input[2] = password input[3] = sessid2
Function Return Values
...
Spacing
Comment, followed by one line of code, followed by one line of space. Example:
-- Store 1 into my_variable my_variable = 1 -- Display the value in my_variable puts(1,my_variable)
Code Process Flow
Avoid using a return/exit in the middle of your code. Every function should have a single return at the end. Use do {} while(0) loops with breaks to control execution. Example:
int VeryLongFunction() { -- Initialize iResult = 0 loop do -- Test something if (condition) then -- Oops. We have to bail break -- Do something -- ... -- Test something else if (another_condition) then -- Oops. We have to bail break end if -- If we're up to here - all is well iResult = 1 end loop -- Return result return iResult end function
Comment Style
EVERY SINGLE LINE of your code must be prefixed with a -- comment. There is no exception to this rule. As for what each comment should say - a nonprogrammer reading your comments top to bottom, should be able to fully understand what the function is doing.
Example:
-- Display Hello World puts(1,"Hello World") -- Check to see if 1 equals 2 if 1=2 then -- 1 does equal 2, the end of the world must be coming -- Display end of the world puts(1,"It's the end of the world as we know it") -- (Else - 1 does not equal 2) else -- We're in good shape -- Display all is well message puts(1,"All is well") end if Every function must be prefixed with a -- comment block outlining input, output and return parameters. Start with a few lines describing what the function does, follow with a list of all input parameters, then all output (pass by reference) parameters and finally the function return value. Include another empty line with -- at the end of the function description Use this block as a template: {{{ -- Attempt to charge customer and process order -- -- Input: -- store_id - Your store ID -- product_codename - The unique product codename -- -- Output: -- order_id - On return will hold order id -- ResultStr - On return will hold Error string -- -- Returns: -- Order ID if successful or 0 if failed -- function do_checkout(atom store_id, sequence product_codename, atom order_id, sequence ResultStr) .. end function
Other important Good Programming Practices
1. Initialize all variables BEFORE using them Example:
function MyFunction() integer iResult = 0; -- Now do something -- ... end function
2. Do NOT rely on global variables.
3. When returning error strings, always return meaningful error strings that a person other than yourself can understand
4. Try to avoid sprinkling new variables into the global scope. Try to keep all variables confined to the scope of a single function
5. Avoid long functions (two pages or more). Split to smaller internal functions as needed and prefix the internal function with an uppercase I for clarity. Example:
function MyLongFunction() -- Wash clothes IWashClothers() -- Now dry them up IDryCycle() -- Notify master that laundry is done INotifyMaster() end function
6. Avoid reusing the same variable in a function for two different purposes (unless it's an i, j, k loop counter)
7. As you develop new functions - "Black box test" your functions in a standalone environment, by calling them from a test shell script. Then after committing your code to the live environment, "White box test" your code by running through a complete cycle start to finish.
- diff to current revision, view current revision history, backlinks
- Last modified Sep 19, 2008 by DerekParnell