Re: Lua style guide ?

[Sean Conner <sean@...>]

It was thus said that the Great Dirk Laurie once stated:
> 
> Non-trivial style means doing things in a certain way, every time,
> so that others on the project (or yourself, next year) feel at home
> with the code. Things like:
> 
> 1. What will our 'require' return? A function? A table? A userdata?

  For the most part, I return a table (a consequence of the Lua 5.1 module
system), although I do have modules that return a function [1] and some a
userdata [2].  Sometimes the module only has one function [3] and it seems
silly to return an entire table with just one function.  But with most Lua
modules returning a table, I can see an argument for always returning a
table.  

> 2. Do we locally cache predefined globals?

  Yes for modules, no for the main program.  When I do cache predefined
globals, how I do it depends upon what it is.  For example:

	local math         = require "math"
	local string       = require "string"
	local io           = require "io"
	local pairs        = pairs
	local tostring     = tostring
	local type         = type
	local print        = print
	local pcall        = pcall
	local getmetatable = getmetatable

  Yes, I tend to require() globals like io, string and table.  To me, it
signals the intent that I want the actual module and while

	local math = math

will work ... eh.  Showing intent is important as well, and this makes no
assumption as to what is loaded and not.  Granted, I can't require() global
functions like type() or pcall(), but if I could, I would.

> 3. How do we code sentinel objects (i.e values that like nil are
> guaranteed not to be equal to anything else)?

  This hasn't really come up with me, so I have no opinion on this.

> 4. Do we make big do ... end blocks in our code in order to
> restrict the scope of locals?

  I do that quite often.  In fact, I'll do things like:

	local somevar do
	  -- code to do a bunch of stuff
	  somevar = ...
	end

to make it clear that there is some non-trivial initialization of a local
variable.

> 5. Do we use some sort of Hungarian notation (i.e. CamelCase,
> quick_brown_fox etc) that advertises what the name will be
> used for)?

  Oh @#$@#$@ no.  I have to suffer with this at work (C and C++ code).  No
thank you.

> 6. Do we consciously conform to ldoc rules for comments?

  Personally, I don't quite care for ldoc [4] as it seems to require too
much typing.  I have my own way of doing it [5] but no way yet to
autogenerate documentation (but I am trying to keep the format consistent to
allow that at some point).

  -spc (There's also the whole namespace issue for modules, but no one seems
	interested in that bugaboo ... )

[1]	https://github.com/spc476/lua-conmanorg/blob/master/src/base64.c
	https://github.com/spc476/lua-conmanorg/blob/master/src/pollset.c

	Some others that haven't been published yet.

[2]	https://github.com/spc476/LPeg-Parsers

	These return LPeg expressions.

[3]	https://github.com/spc476/lua-conmanorg/blob/master/lua/getopt.lua

[4]	I'm checking the source code itself to LDoc and I'm not finding much
	in the way of LDoc in it.  It seems that only "public" methods have
	it, no local functions.

[5]	As seen in here: https://github.com/spc476/CBOR/blob/master/cbor.lua