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

[Hisham <h@...>]

On 10 June 2016 at 23:40, Philipp Janda <siffiejoe@gmx.net> wrote:
> Am 10.06.2016 um 22:38 schröbte Hisham:
>>
>>
>> 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.
>
>
> I disagree with that one. One main benefit of "the new way" of using modules
> is that you can have short local aliases for long module names. We need long
> module names because those names are global, so you have to be careful to
> avoid naming conflicts.

Well, we have namespaced modules to solve naming conflicts (e.g.
`luarocks.build.cmake`).

> I often use `local L = require("lpeg")` *or* `local L = require("srfi1")` (a
> module for linked lists). Lpeg code often has multiple module function calls
> in the same expression, so a short namespace variable keeps things readable.

Considering lpeg code "readable" is an acquired skill (much like
regexps). But if one is willing to abbreviate for conciseness, I'd go
all the way and do `local Ct = lpeg.Ct` and the like instead, near
where they are used. Even Roberto's examples in the website all use
`lpeg.` plus the occasional `local V = lpeg.V` where needed:
http://www.inf.puc-rio.br/~roberto/lpeg/lpeg.html#ex — and I think
they are a good standard for clear lpeg code.

> I don't yet know what I will do when I need both of them in the same file
> ...

I rest my case. :)

> Often I will re-use the function name prefix of the C functions as Lua
> namespace, like `fl_run()` (C code) -> `fl.run()` (Lua code).
> Also, `local 30log = require("30log")` won't work anyway.

I take this example as a case against using module names that aren't
valid identifiers. This just made me realize (and test to verify) that
something like require("céu") actually works, even though céu is not a
valid identifier (though doing this is probably asking to have trouble
in legacy systems — yes, there are still non-UTF-8 systems running out
there).

>> 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).
>
>
> LuaSocket isn't a socket either. Both are modules that contain functions
> that cover a certain field -- filesystem functions or socket functions,
> respectively.

OTOH, LuaSocket is a library for creating sockets, and LuaFileSystem
is not a library for creating filesystems. :) I do see your point
though. It still confused me back then. :)

> I would have expected `require("filesystem")` instead of `require("lfs")`
> (similar to `require("socket")` or `require("posix")`), though. The "lua"
> prefix is pretty redundant in a `require` call,

Agreed. And I'd dare say that nowadays the Lua* or L* prefixes seem
pretty redundant in a project name as well, since a project Foo for
Lua can be easily found looking for "foo" in luarocks.org or searching
the web at large for "lua foo". I but do see that a developer would
still rather call their repo something like github.com/user/lua-foo,
especially when it's a bindings module.

> but the "lfs" feels like a
> completely new (and unrelated) name -- especially considering that LuaSocket
> and lsocket are two separate projects.
> Btw., I suspect that the module was named "lfs" because in Lua 5.1 you would
> automatically get a global variable with the same name as the module, and
> "luafilesystem" (or "filesystem") as a variable name was just a bit too long
> ...

Sure, lfs is a pretty old module, and I'm aware that the explanation
is historical. And no, I have no idea what I'd call LuaFileSystem if I
were to name it!

-- Hisham