Commenting

When it comes to commenting code, you must find a balance between too much and too little. Comments are considered documentation that should be modified as a part of regular maintenance or development.

In general, it is best to assume the reader understands the basics of Lua, so we recommend using comments in two areas:

At the top of each module/function, you should provide a “header” comment block to document the history of the code:

-- ----------------------
-- This module is created to do this and that
--
-- (c) 2012 iNTERFACEWARE Inc.  All rights reserved
--
-- 01 Jan 2012 Bob Smith first iteration
-- 02 Feb 2012 Ian Flemming  Added HL7 Spy information
--
-- ----------------------

You can create detailed Help Files (*.help) for any custom function you create. This is where majority of the documentation and guidance should be accessed.

However, significant blocks of code should be commented with what they accomplish, not how they accomplish it. For example:

Outline a major steps in the logic of the code; or
How a function is called if that can change and what it returns or why if that is appropriate.

These comments can act as an important knowledge transfer tool for future team members and help them find areas of concern or interest.