conventions.txt

-----------------------------------------------------------------------------
-- Conventions used when writing the source of Assistant
-----------------------------------------------------------------------------

All modules and classes classes should be listed in their respective folder and any
functions that they own should be listed in their respective folder and in separate files
	: (In example, Sheet.lua owns sheet/* files and subfolders)

Public functions should be listed in a different folder than internal functions
	: (In example, functions at sheet/ are internal, functions at sheet/public are public)

Depending in the type, files containing functions/sections
should include comments for each function/section

1.  Single function files

      Contain two or more lines explaining:
        a) Who owns this function ( such as sheet.lua )
        b) How does this function appear as
            : such as "define_class()"
        c) Brief line(s) containing information about the function
            : "-- Checks if all the arguments passed to class:new() are of an accepted type."

      The function is declared in return
        : "return function() end"

2.  Indexing files
      Contain two lines explaining:
        a) Who owns the functions returned by index and
        b) Whats the purpose of the functions and if they are public/internal or both
            : "-- <class name> class functions" (If there's both internal and public functions)
            : "-- Public <class name> functions"
            : "-- Internal <class name> functions"

3.  Definition files
      Contain comments at every section explaining in detail whats the purpose of those definitions

      The sections are closed between separators and every section has a comment at the top
        : (Like in definitions.lua)

Internal Assistant variables in the global scope are defined and documented in "definitions.lua"

There's a few guidelines relating to code style to make Assistant source more readable:

1.  Indents
      Using tabs, indents should be 2 spaces width

2.  Line breaks
      Place an empty line right before any comment
      Place an empty line before and after any multiline
      Place an empty line before and after sections (related lines of code)
        : If you want to know how to determine sections, mimic Sheet.lua
      Place an empty line before and after declaring functions
        : This only applies if the function is nested in other function or in a table
	  You should also break long tables and align when declaring (i.e. index.lua)

3.  Comments
      Make everything as concise and short as possible

4.  Methods used
      There's no general guidelines, but keep everything as short and readable as possible
      without sacrificing performance (you should also split long function calls)

5.  Variable names
      The variable name should be self explanatory all the time

6.  lower case / UPPER CASE
      Constants should be all upper case and snake case (CLASS_PATH)
      All variables are pascalCase
      Parameter identifiers can be snake_case (for example, parameter type "named_args")

7.  and-or ternary
      You should split these only if there's more than 1 conditional involved
        : (true and true or false) has 1 conditional
        : (false and true or (true==true and false or true)) has 2 conditionals

        Therefore you split it like this:
          (
            false and true
            or (
              true == true 
	      and false
              or true
            )
          )

        This makes the code more readable (in case a regular if would be too extensive), 
        but if you can avoid these, please do