This page describes the standard coding style that Sputnik is moving towards.

Not all of Sputnik's code follows this at the moment, but we are getting eventually. When in doubt, go with what this page says over what you see done in practice.

Indentation

All indentation must be done with 3 spaces. (That's "Lua style", don't ask why.) No tabs. Feel free to use the following vim modeline when working in the core files:

-- vim:ts=3 ss=3 sw=3 expandtab

Comments

Module Comments

Each module should start with a comment, which should precede everything else:

-----------------------------------------------------------------------------
--  This is the reference implementation for an authentication module.  It 
--  implements all of the core functionality that Sputnik will expect from a 
--  drop-in-replacement.
--
--  (c) 2008 Jim Whitehead II (j...@....com)
--
--  License: MIT/X, see http://sputnik.freewisdom.org/en/License
-----------------------------------------------------------------------------

Each line of the comment should start with "-- ". The comment should include the name of the the authors / copyright holders and a link to the license. (If you are contributing a complete module, then put your name.) The license must be MIT/X.

Function Comments

All exposed functions should be preceded by LuaDoc comments. The comments should wrap at 78 characters. All parameters except for "self" should be documented. The explanation of the parameters should start at column 26.

-----------------------------------------------------------------------------
-- Creates a new instance of the authentication module for use in sputnik.
--
-- @param sputnik        the sputnik instance to use for storage.
-- @param params         [optional] a table of configuration paramaters (the 
--                       requirements of this table depend on the specific 
--                       module implementation).
-- @return               an instance of Simple.
-----------------------------------------------------------------------------

Optional parameters should have their descriptions prefixed with [optional].

OOP Style

Object Construction

Sputnik uses "classes" whenever possible, rather than functional closures. The classes should be defined as follows:

local Simple = {}
local Simple_mt = {__metatable = {}, __index = Simple}

The class table and the class metatable should both be local, unless there is a good reason for them not to be. An instance of the class should be created with a new() function. In many cases this should be the only exposed function in the module. This function should put together a table representing the instance, attach the class metatable to it, then return it:

function new(sputnik, params)
   -- Set up default parameters
   params = params or {}
   params.node = params.node or "_passwords"
   -- ... skipped some code ...

   local obj = setmetatable({}, Simple_mt)
   obj.sputnik = sputnik
   obj.node = params.node
   -- ... skipped some code ...

   return obj
end

Method Definitions

All the method should be defined as follows:

-----------------------------------------------------------------------------
-- Returns whether or not a given username exists in the authentication 
-- system, without any further information.
--
-- @param  username      the username to query.
-- @return               a boolean showing whether or not the username exists
--                       in the system.
-----------------------------------------------------------------------------
function Simple:user_exists(username)
   local users = load_users(self.sputnik, self.node)
   return type(users[username]) == "table"
end

In other words, the "self" parameter is not made explicit but is defined implicitly with the use of ":".

Modules

All Sputnik modules are created with the "module" function introduced in Lua 5.1:

module(..., package.seeall)

This should go right after the module comment.