Sputnik: Coding Standard

Anonymous users must enter captcha below.

Don't put anything here

Page Parameters

Page Name (for URL)

Don't put anything here

Page Title

Don't put anything here

Show Advanced Options

Page Content

<span class="teaser">
  This page describes the standard coding style that Sputnik is moving towards.
</span>

<i>
  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.
</i>

## 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.

Don't put anything here

About this Edit

Minor Edit

Edit Summary

Don't put anything here