code style guidelines

[jlaurens]

The source code follows some implicit guidelines, more or less respectfully. They are outlined here along with some complements and will eventually end up somewhere in the repository.

Notice that the following aims to cover only the backend, not the user interface (what is defined by l3build.dtx).

Notice that this is more about better practice than definitive rules. An author may deliberately choose different practice because it serves his purpose more efficiently, this should be honored as far as possible. [ADDED]

These guidelines will motivate some cosmetic changes in order to both help the reading and avoid some kind of inconsistencies. Cosmetics is the subject of the next section. The other section will be devoted to code design, it is actually WIP.

NB: I opened the discussion without knowing issue#135.

Cosmetics

General rules

• indentation corresponds to 2 spaces, not a tab character.
• lines should be less than 80 characters long.
• -- starts inline comments
• --- starts documentation comments

The documentation for the frontend belongs to l3build.dtx whereas the documentation for the backend is inlined
and concerns the developers.
Roughly speaking the backend is everything that is not documented in the l3build.dtx.

Naming convention

• variable and function identifiers use snake_case
• constant identifiers use MACRO_CASE
• _ is reserved for a dummy variable (a variable that must be declared but is never used)

Notice that identifiers with two leading underscores and MACRO_CASE identifiers with one leading underscore are reserved by the system.

Variable names are chosen to reflect what they are modeling.
One letter variable identifiers should be limited to short scopes, typically those which entirely fit within one screen. [ADDED]

Syntax shortcuts

• dir = dir or "." for if not dir then dir = "." end

This is usual practice, see PIL.

• function calls always use parenthesis: foo("bar") instead of foo "bar", [ADDED]

Indentation and breaks

The lines in a block are indented one level deeper relative to the container.

Branch and loop

if blocks with long conditionals should separate clearly the body from the condition.
The same holds for loops. For that do and then keywords can be placed on their own line,
for example

for _,tab in pairs(
  {bibfiles,demofiles,docfiles,pdffiles,scriptmanfiles,typesetlist}) do
  copyfiles(tab,docfiledir)
end

could be replaced by

for _,tab in pairs({
  bibfiles, demofiles, docfiles, pdffiles, scriptmanfiles, typesetlist
}) do
  copyfiles(tab,docfiledir)
end

long lines

• line breaks should occur before a binary operator,
• line continuation should be indented relative to the line beginning.

It might be advisable to align material vertically, in particular for long function calls and string concatenation:

return runcmd(makeindexexe .. " " 
        .. makeindexopts
        .. " -o " .. name .. outext
        .. (style and (" -s " .. style) or "")
        .. " -t " .. name .. logext .. " "  .. name .. inext,
        dir,
        {"INDEXSTYLE"}
)

Notice that line breaks correspond here to each new -... option.
Also, the trailing ) indicates the end of the last instruction with the same indentation.

Horizontal space

Space is necessary to separate code atoms whereas too much space may render the code difficult to read.
Adopting LaTeX3 point of view seems reasonable.

In general:

• put a space after a comma and a colon but not before
• put a space around semicolons and binary operators, except single dot

If it does not widen the lines too much:

• put a space after opening delimiters or before closing ones, except possibly between delimiters.

Vertical space

• comments allow to separate blocks of instructions better than blank lines
• the ; operator allows to group related instructions on one single line as an atom and should be used sparingly

For example, to iterate over the characters of the string str, one may need a while loop instead of a for loop

local i = 0
while i < #str do
  i = i + 1 ; char = str:sub(i, i)
  ...
end

Using ; makes sense here because the looping instructions were gathered on one line.

quoting material

• single quote or double quotes should be used consistently within main function blocks at least.
• double quotes are more visible whereas single quotes and backticks are very similar
• long string literals allow to print multiple lines all at once (less print and less \n)

tables

• {} for void tables (like \TeX{} void groups)
• { sourcefiledir, docfiledir } for lists
• { foo: ... } replaces { ["foo"]: ... }
• foo.bar replaces foo["bar"]

The long syntax is used for the global options table to emphasize that field names are exactly command line option names. [ADDED]

Code design

• some functions may encounter a runtime error. In that case they return an "error level": 0 when the function terminates properly, a non 0 error code number otherwise. [CHANGED due to code base]
• The functions defined by the user in the various build*.lua may also return nil instead of 0 on proper termination. [ADDED]

Naming variables

type

The variable name can include an indication of the variable type when it is not easily guessed.
For example name is a string and name_list is a table array of strings.
i, j, k are reserved for integers.
n stands for name.

Function declaration, function call

When a function declaration relies on formal arguments, then the corresponding function calls should use the same names.
In case of conflicting situation, appending or prepending some identifier to the argument name can make things more clear. With declaration

function foo(name, flag)
...
end

one can call

local name = "blablabla"
local my_flag = false
foo(name, my_flag)

File related

Files are covered by 3 kinds of variables: the file name, the file handle and the file content.

The file name is covered by variables named containing file, f or name.

The file handle is covered by fh or any variable named with a _fh suffix.

The file contents is referenced by any reasonably named variable.

Usage

name	usage
file	file name (no directory separator)
base	idem
name	idem
dir	dir path (may include directory separators)
path	path (may include directory separators)

Paths

Paths are strings meant to represent some location on the file system.
Supported file systems are Windows and various unix including Apple's OS X.
To ensure cross platform compatibility, only regular files and directories are supported.
Symbolic links, desktop shortcuts and aliases are not supported.

The path separator in texlua is "/" but when talking to the host system it must be adapted.

[josephwright]

That's quite an impressive list: I think some of it is to me at least more-or-less implicit :)

General rules

* indentation corresponds to 2 spaces, not a tab character.

I'm a LaTeX programmer, so tabs just become spaces anyway ;)

* lines should be less than 80 characters long.

* `--` starts inline comments

* `---` starts documentation comments

I'm not sure what you mean here: documentation should be in the .dtx.

Naming convention

* variable and function identifiers use snake_case

* constant identifiers use MACRO_CASE

The only capitalised variable I've ever seen in Lua code is _G: I'm wary of breaking with the language conventions. Is this seen elsewhere (ConTeXt?).

Syntax shortcuts

* `dir = dir or "."` for `if not dir then dir = "." end`

This is from PiL, so I think is a completely standard Lua idiom.

Indentation and breaks

The lines in a block are indented one level deeper relative to the container.

Branch and loop

if blocks with long conditionals should separate clearly the body from the condition.
The same holds for loops. For that do and then keywords can be placed on their own line,
for example

for _,tab in pairs(
  {bibfiles,demofiles,docfiles,pdffiles,scriptmanfiles,typesetlist}) do
  copyfiles(tab,docfiledir)
end

could be replaced by

for _,tab in pairs({
  bibfiles, demofiles, docfiles, pdffiles, scriptmanfiles, typesetlist
}) do
  copyfiles(tab,docfiledir)
end

long lines

* line breaks should occur before a binary operator,

* line continuation should be indented relative to the line beginning.

It might be advisable to align material vertically, in particular for long function calls and string concatenation:

return runcmd(makeindexexe .. " " 
        .. makeindexopts
        .. " -o " .. name .. outext
        .. (style and (" -s " .. style) or "")
        .. " -t " .. name .. logext .. " "  .. name .. inext,
        dir,
        {"INDEXSTYLE"}
)

Notice that line breaks correspond here to each new -... option.
Also, the trailing ) indicates the end of the last instruction with the same indentation.

I've been a bit inconsistent here: trying to find what looks best!

Horizontal space

Space is necessary to separate code atoms whereas too much space may render the code difficult to read.
Adopting LaTeX3 point of view seems reasonable.

In general:

* put a space after a comma and a colon but not before

* put a space around semicolons and binary operators, except single dot

* put a space after opening delimiters or before closing ones, except possibly between delimiters.

I think I started with a space after , in e.g for k, v in, but then spotted that other Lua code seems to omit it. I'd like to know what the 'usual' convention is.

Vertical space

* comments allow to separate blocks of instructions better than blank lines

* the `;` operator allows to group related instructions on one single line as an atom

Huh?

For example, to iterate over the characters of the string str, one may need a while loop instead of a for loop

local i = 1
while i < str:len() do
  i = i + 1 ; char = str:sub(i, i)
  ...
end

The looping instructions were gathered on one line.

I'm not keen on that myself, but then I also find Lua's foo, bar = 1, 2 borderline.

quoting material

* single quote or double quotes should be used consistently within main function blocks at least.

* double quotes are more visible whereas single quotes and backticks are very similar

* long string literals allow to print multiple lines all at once (less `print` and less `\n`)

Probably just me: I really don't like the [[ ... ]] business as it doesn't do indenting properly (as Lua doesn't concatenate spaces at the start of lines). I actually prefer to see \n when a newline is expected in output. But of course if the consensus is to use [[ ... ]]`, that's what we'll do.

tables

* `{}` for void tables (like \TeX{} void groups)

* `{ sourcefiledir, docfiledir }` for lists

* `{ foo: ... }` replaces `{ ["foo"]: ... }`

* `foo.bar` replaces `foo["bar"]`

options table I still feel should use the lattr method.

Code design

* some functions may encounter a runtime error. In that case they return a non 0 number. Returning 0 or `nil` means no error. This is critical for functions defined by the end user in her own `build.lua`.

Fine with me: mainly lacking due to oversight early on.

[jlaurens]

I have updated the first message to take most of your remarks and addenda into account

• added a remark on the backend documentation, the code is already documented
• "Notice that this is more about better practice than definitive rules."
• about MACRO_CASE, added: some identifiers are reserved by lua (for example _VERSION)
• added the reference to PiL, however this is not limited to lua and may seem weird for some people
• I changed a bit the ; section. I was not clear, the idea was "you can use ; but only when it makes sens"

Some precision:

• there is no real convention about spaces in lua, PiL uses spaces after commas.
• the [[]] business is not a requirement, but with syntax coloring it is very handy. The question is not to use [[]] every time, but to use is if it reads better.

[jlaurens]

About the foo, bar = 1, 2 multiple assignment. This is also available in python, and in swift AFAIK.

Sometimes Lua syntax goes against cultural intuition, for example

local a, b = 1

is a shorcut to

local a, b
a = 1
b = nil

One would expect to end up with b = 1. It may help thinking that comma has higher priority that equals.
tuple assignment is more than syntactic sugar. Of course swapping becomes easy

a, b = b, a

but more importantly, tuple assignment is required to catch the output of the match command when there are more than one capture groups.

[josephwright]

I've never used a,b = 1 as I think it's best to be explicit. Personally, the only time I've used it is with a function that returns multiple values: name,path = splitpath(file) (that is not so bad).