Commenting

In theory, commenting is like cheese on a pizza: you just can’t have too much! In practice, you must find a balance between too much and too little. What’s more, any documentation should be modified as a part of maintenance or additional development. Specifically, comments should not be used to duplicate the code.

It is acceptable to assume that any future reader has a basic understanding of Lua, so we will use comments in three areas:

• To document the history and ownership of the code
• To provide general guidance as to how the code works
• To explain “tricky bits”

Ownership and History

At the top of each module/function, you should provide the following “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
--
-- ----------------------

This is particularly useful for production code as it gives us insight into a) who owns the code, and b) who has worked on it.

General Guidance

Significant blocks of code should be commented with what they accomplish, not how they accomplish it. This focus helps follow-on programmers find areas of concern or interest.

Tricky Bits

Most of the time, Lua is quite readable. As such, it’s safe to assume a certain level of understanding from all of its readers. That said, with developers being developers, sometimes some rockstar programmer will create code that is too elegant or too cool to be readily readable. In such cases, you must use comments to clear up any confusion that us mere mortals might encounter.