Create style.lua(9)

[kevans]

Summary

Named similarly to, for example, style.Makefile(5).

I think this covers the style we've agreed on so far. Parenthesizing is left out until we make a decision and get everything up to snuff accordingly, though I lean towards cem@'s proposed "drop the parentheses around conditionals".

[cem]

First pass.

Typographic nit: .Va stands for "variable name." A lot of these uses are not that. Check out mdoc(7) for more descriptive commands. .Li (single-line literal) can be a last-ditch
stand-in if nothing better fits, but there are probably better commands for many of these.

share/man/man9/style.lua.9

47–48

I would amend this. Having blocks of commentary is not bad. But Lua's multi-line comment syntax is godawful.

Maybe:

Use the single-line comment style for every line in a multi-line comment.

54–56

It isn't clear to me what this is describing.

Is it:

<blank>
require1()
require2()
<blank>

Or:

<blank>
require1()
<blank>
require2()
<blank>

I prefer the former (like C includes).

63

Ok this example makes it more clear :-). In which case, I suggest clarifying or removing the earlier language.

80

It applies to anything with a "metatable," as I understand it, although my Lua knowledge is super weak. I'd like to confirm that, and if correct, mention that rather than strings in particular.

84

Can just drop "where appropriate."

85

I'd like to rephrase this but I can't think how off the top of my head.

87

I don't understand this sentence.

88

I think I understand this one, but am not sure. We're basically disallowing single-line conditional statements or loops, right? I'd like to reword this one too.

92

s/-wide/ scope/ maybe

93

It would be consistent with C. What's the harm?

96

Hm, and this is the opposite of C style(9)

[kevans]

share/man/man9/style.lua.9

85

Perhaps rewrite to: "Testing for nil should be done explicitly, rather than testing for nil as a boolean" ?

88

Yeah, these two were bad, but they're saying the same thing.

93

I think the main thing I'm trying to avoid here is multiple declarations with initialization (another point we'll hit later). I much prefer the C form of this in general. I'd really prefer not seeing this kind of stuff pop up everywhere:

local a, b = 5,6

except with more complex expressions than '5' and '6'.

96

Only bits and pieces were inspired by the parts of style(9) that I agree with. I don't see any reason we shouldn't do initialization at declaration time, especially in this higher-level context of Lua.

[kevans]

• Re-worded some things
• Most uses of .Va got converted to something else: .Ic for keywords (style(9) does this), .Fn for functions, other uses removed

[cem]

share/man/man9/style.lua.9

85

Works for me.

93

How do you feel about disallowing multiple definitions with initialization on one line, but allowing multiple definitions (absent initialization)?

96

I'm ok with stuff like constants, but I don't like seeing function calls that can have side effects in the middle of declarations. But, I'm ok being overruled on this.

[kevans]

share/man/man9/style.lua.9

93

No problems at all with multiple definitions lacking initialization. It might be better to go with the C style(9) rule here of initialization being separate under all circumstances just to avoid the possibility of seeing cases like this. I would've felt much better and more strongly about it if the lua syntax allowed local a = 4, b = 3;

[cem]

share/man/man9/style.lua.9

79

I think maybe not anything, after a little research. Metatables do not have to provide method functionality, it's just one of the things they can be used for.

http://lua-users.org/wiki/ObjectOrientationTutorial

The method calling convention style is really applicable to *tables* that happen to have methods — either directly on the table, e.g.:

$ lua
> a = {}
> function a.foo(self)
>> print(tostring(self))
>> end
> a.foo(a)
table: 0x562242a00680
> a:foo()
table: 0x562242a00680

OR via metatable __index that points to some sort of class table (essentially acting as a vtable).

So I think I would be less specific, and maybe say: "This is applicable to objects with methods. Strings are a commonly-used example of objects with methods."

83

I think there's some verb tense disagreement here — testing, tested. I'd just remove "tested" from the second clause: "…rather than as a boolean expression."

90

Maybe append: "Lines containing multiple variable declarations without initialization are ok."

94–96

I might just kill this sentence. Some parts match, some parts don't match. What are we trying to tell the reader?

[jilles]

share/man/man9/style.lua.9

88–90

I agree that things like

local a, b = "long expression 1", long.expression_2

should be avoided, but how about capturing multiple return values like

local data, err = something_that_can_fail()

This seems a common pattern, and also some standard functions return multiple values.

96

I also like "initialization at declaration time", which includes declaring variables as late as possible. However, I don't think this is related to the higher-level context since C99 and newer support the same paradigm. Instead, Lua being a different language allows introducing this paradigm.

I googled for various Lua style guides and they all happily call functions from initializers.

I don't think we should bend Lua to KNF.

[kevans]

share/man/man9/style.lua.9

88–90

Right, no objections to that either- I mainly don't want to be sorting through expressions to decide what these things are being initialized to. If it's a trivial expression or a function with multiple return values, I consider that easy and readable as the latter situation is a documented kind of thing. I know to expect this function returning multiple values, and I know what those return values mean.

96

That's something else I hadn't touched on here, either. We don't mention it, but we do often-times in current scripts declare things just as late as needed, or within narrower scopes than the entire function. This is also a thing I'd like to maintain.

[cem]

share/man/man9/style.lua.9

88–90

I have no objection to local data, err = multiple_return_function(); or more broadly, for tuple-unpacking in general: local a, b, c = unpack({1,2,3});.

I still object to tuple unpacking in tandem with long tuple literals (jilles' "long expression" example above), which I think we're all on the same page about.