Re: some random thoughts on naming conventions for Lua libraries/modules

[Hisham <h@...>]

On 10 June 2016 at 02:14, 书呆彭, Peng Yi <nerditation@outlook.com> wrote:
> there are various kinds of Lua libraries(just to say some, incomplete, of
> course):
>
>    * binding to other libraries/runtimes/APIs written in other languages
> (C/C++/Go/dotNet etc.).
>
>      e.g. wxLua, Lua-SDL2, LGI, LuaCOM, LuaInterface, lposix, etc.
>
>    * rewrite/resemble/reimplement of libraries written in other languages.
>
>      e.g. LuaUnit, alt-getopt, lustache, lspec,
> markdown.lua[https://github.com/mpeterv/markdown], etc.
>
>    * Lua special or Lua centric libraries (including compatibility backport
> libraries).
>
>      e.g. lpeg, strictness, penlight, lualanes, 30log, bit32, compat52, etc.
>
>    * frameworks and applications which are implemented and can be used as
> libraries.
>
>      e.g. lake, moonscript, lapis, etc.
>
>
> looking at these libraries, I find the names are inconsistent, among which I
> think some are
>
> due to technical restrictions, some are simply arbitrarily chosen.
>
>
> for library/project names (usually the name you give luarocks to install),
> there exists:
>
>     XXX, Lua-XXX, lua-XXX, luaXXX, lXXX, LXXX, XXXLua, XXX-Lua, etc.
>
> for module names (that is, the parameter you passed to `require`), there
> exists:
>
>     xxx, lxxx, luaxxx, xxxlua, etc.
>
> and for some projects, the namespace for functions, variables and constants
> in the document
>
> is inconsistent with (sometimes even wrong) the module name.
>
> for example,
>
>     IUPLua -> (no luarock) -> local iup = require 'iuplua'
>     wxLua -> (no luarock) -> local wx = require 'wx'
>     Lua-SDL2 -> luarocks install lua-sdl2 -> local SDL = require 'SDL'
>     LuaFileSystem -> luarocks install luafilesystem -> local lfs = require
> 'lfs'
>     LuaGL -> luarocks install luagl -> local gl = require 'luagl'
>
>
>
> I am NOT suggesting any naming schema or guidelines here. I have my personal
> taste too.
> I don't mean to start a debate, or even a war about this. I am just curious
> about what's
> other people's opinions on this topic. this helps me to choose names when I
> release
> my code to the public.

This is a very interesting topic.

LuaRocks enforces that rockspec names are all-lowercase, but includes
a "package" field in the rockspec format where you can specify the
preferred capitalization of the project name for display purposes
(package:lower() must match the name in the rockspec).

In my opinion, it's important that the name of the project matches the
name of the rockspec (as all of the examples you mentioned above do,
so I feel I've been successful establishing a good culture at that),
and that the name of the module matches the name of the variable it is
being required to.

My reasoning for the latter is that using inconsistent, `local x =
require "y"` types of names is counterproductive: especially when
looking at someone else's code, having to keep in mind how a module
author decided to call a well-known library is an avoidable extra
cognitive load, and having to skim back and forth to look at the
require() list is annoying.

For code I write, I also try to have the project/rockspec name match
the name of the main module, using lowercase for module names and
snake_case for methods (I use TitleCase only when doing OOP).

Consistency is important: I see people complain about "luafilesystem
vs lfs" all the time (we might add a module index to LuaRocks in the
future so that `luarocks install lfs` does the right thing, but it's a
bit harder than it seems at first glance). I'd say this was an
unfortunate decision when LuaFileSystem was first written (not to
mention that the name of this library is super confusing, since
LuaFileSystem is not, well, a file system — this is not a rhetorical
point, it _did_ leave me puzzled the first time I saw the name, back
in the day).

So, in short, the way I try to do things is to keep it simple:

project Foo, rockspec foo, local foo = require("foo")

I think it's the path of least surprise for users of the project. :)

-- Hisham