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 ↗

(On Diff #39459)

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 ↗

(On Diff #39459)

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 ↗

(On Diff #39459)

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

80 ↗

(On Diff #39459)

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 ↗

(On Diff #39459)

Can just drop "where appropriate."

85 ↗

(On Diff #39459)

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

87 ↗

(On Diff #39459)

I don't understand this sentence.

88 ↗

(On Diff #39459)

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 ↗

(On Diff #39459)

s/-wide/ scope/ maybe

93 ↗

(On Diff #39459)

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

96 ↗

(On Diff #39459)

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

[kevans]

share/man/man9/style.lua.9

85 ↗

(On Diff #39459)

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

88 ↗

(On Diff #39459)

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

93 ↗

(On Diff #39459)

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 ↗

(On Diff #39459)

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 ↗

(On Diff #39459)

Works for me.

93 ↗

(On Diff #39459)

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

96 ↗

(On Diff #39459)

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 ↗

(On Diff #39459)

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

78 ↗

(On Diff #39471)

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."

82 ↗

(On Diff #39471)

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."

89 ↗

(On Diff #39471)

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

93–95 ↗

(On Diff #39471)

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

87–89 ↗

(On Diff #39471)

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 ↗

(On Diff #39459)

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

87–89 ↗

(On Diff #39471)

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 ↗

(On Diff #39459)

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

87–89 ↗

(On Diff #39471)

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.