Historical CodingConvention, Revision 4


This page is under development. The content is not official policy or a recommendation.


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.

Search



Quick Links

User menu

Not signed in.

Misc Menu