Lua Style Guide ?

classic Classic list List threaded Threaded
96 messages Options
12345
Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Peter Aronoff
Russell Haley <[hidden email]> wrote:
> I found your code in Moses very readable and well structured but
> I noticed you use '_' for some 'root' level variables (for lack of
> a better term). My understanding (I think I read it somewhere)  was '_'
> was supposed to be used in cases where you weren't going to use the value
> like in:

Re "I think I read it somewhere". The use of _ for unused/throwaway
variables is definitely a convention in Lua. Maybe you read this in
Roberto's Programming in Lua? "Usually, I reserved the identifier _ (a
single underscore) for dummy variables" (page 5 in the 3rd edition). But
you may have read it in the wiki's style guide or a bunch of other places.

If I had to guess, the original tendency may have started with PiL, but
maybe people who have been in the community longer would know better.

Peter

--
We have not been faced with the need to satisfy someone else's
requirements, and for this freedom we are grateful.
    Dennis Ritchie and Ken Thompson, The UNIX Time-Sharing System

Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Russell Haley
In reply to this post by Roberto Ierusalimschy
Sorry for the top post. 

Often when I think I'm being clever in code I put extra comments around it because the likelihood of a difficult bug will be particularly high in that area. ‎Perhaps these areas in my code require more comments. Or better yet, more linefeeds. :-/

But ‎I found an example in code last night that I think works. I had to check all three variables in a function for type. One line if-then-else's were very effective for reducing the lines and creating a block of code that I can recognize without having to read. 

As I said, I think the problem dictates the style. I also think my Lua code is very clever. XD

Sent from my BlackBerry 10 smartphone on the Virgin Mobile network.

  Original Message  
From: Roberto Ierusalimschy
Sent: Wednesday, June 7, 2017 5:32 AM
To: Lua mailing list
Reply To: Lua mailing list
Subject: Re: Lua Style Guide ?

> [...] One of my
> current favorites in Lua is if/then/else on one line, which will
> rarely fit in 80 characters:
>
> if table.value == "another value" then number1 = number1 + 6 else
> number1 = 0 end

That explains a lot :-)

-- Roberto


Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Hisham
In reply to this post by Peter Aronoff
On 7 June 2017 at 09:41, Peter Aronoff <[hidden email]> wrote:

> Russell Haley <[hidden email]> wrote:
>> I found your code in Moses very readable and well structured but
>> I noticed you use '_' for some 'root' level variables (for lack of
>> a better term). My understanding (I think I read it somewhere)  was '_'
>> was supposed to be used in cases where you weren't going to use the value
>> like in:
>
> Re "I think I read it somewhere". The use of _ for unused/throwaway
> variables is definitely a convention in Lua. Maybe you read this in
> Roberto's Programming in Lua? "Usually, I reserved the identifier _ (a
> single underscore) for dummy variables" (page 5 in the 3rd edition). But
> you may have read it in the wiki's style guide or a bunch of other places.
>
> If I had to guess, the original tendency may have started with PiL, but
> maybe people who have been in the community longer would know better.

This practice comes from other languages. In Haskell function
declarations, for example, _ means a "don't care" pattern:

printFirstInList [] = "list is empty"
printFirstInList (x : _) = "first element is " ++ show x

Here, the rest of the list is being "discarded" with a _. Haskell
actually enforces it so that you can't "use" _ (it's only a pattern
and not actually a variable). In Lua, however, that is a variable, so
that is more of a notation convention:

for name, _ in pairs(entries) do
   print("name: " .. name)
end

In this traversal, only keys are being used and not values. _ being a
regular variable means that nothing would stop us from doing print(_),
but it's a convention that when we declare _ we mean we won't ever use
its value.

Likewise, I sometimes also do this:

local _, val = function_for_which_i_only_need_the_second_result()

-- Hisham

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Jorge Eduardo
Why do not we agree on an official style guide for the Lua language?
Something that improves the readability of the code, like PEP-8 for Python?

Best regards,

Jorge Eduardo

Em 7 de jun de 2017 20:51, "Hisham" <[hidden email]> escreveu:
On 7 June 2017 at 09:41, Peter Aronoff <[hidden email]> wrote:
> Russell Haley <[hidden email]> wrote:
>> I found your code in Moses very readable and well structured but
>> I noticed you use '_' for some 'root' level variables (for lack of
>> a better term). My understanding (I think I read it somewhere)  was '_'
>> was supposed to be used in cases where you weren't going to use the value
>> like in:
>
> Re "I think I read it somewhere". The use of _ for unused/throwaway
> variables is definitely a convention in Lua. Maybe you read this in
> Roberto's Programming in Lua? "Usually, I reserved the identifier _ (a
> single underscore) for dummy variables" (page 5 in the 3rd edition). But
> you may have read it in the wiki's style guide or a bunch of other places.
>
> If I had to guess, the original tendency may have started with PiL, but
> maybe people who have been in the community longer would know better.

This practice comes from other languages. In Haskell function
declarations, for example, _ means a "don't care" pattern:

printFirstInList [] = "list is empty"
printFirstInList (x : _) = "first element is " ++ show x

Here, the rest of the list is being "discarded" with a _. Haskell
actually enforces it so that you can't "use" _ (it's only a pattern
and not actually a variable). In Lua, however, that is a variable, so
that is more of a notation convention:

for name, _ in pairs(entries) do
   print("name: " .. name)
end

In this traversal, only keys are being used and not values. _ being a
regular variable means that nothing would stop us from doing print(_),
but it's a convention that when we declare _ we mean we won't ever use
its value.

Likewise, I sometimes also do this:

local _, val = function_for_which_i_only_need_the_second_result()

-- Hisham

Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Daurnimator
In reply to this post by Russell Haley
On 7 June 2017 at 01:41, Russell Haley <[hidden email]> wrote:
> I am biased, but I find daurnimators code so elegantly simple it 'has no style'.

Thanks!
I wouldn't say it has no style though: my coding style has evolved
over the years.
Back in 2008ish I wrote this up about my coding style at the time:
https://code.google.com/archive/p/lomp/wikis/CodingStyle.wiki
However much of my preferences have now changed.

If I thought anyone would read+follow a coding style guide, I might
keep one updated. But I've learnt that no one *does* read them: it's
more practical to have a "house style" for a project, and catch
anything that deviates in a pull request.
The only time a guide works is when they have tooling to enforce it:
however for such a tool to be useful (no one agrees on style!) it has
to be tremendously configurable.
Even then you have to persuade people to use the tooling (see how
often people use astyle or clang-format).

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Sleepers Tang
In reply to this post by Jorge Eduardo
It's hard to have an official style guide for Lua.
I believe the best style for Lua should consider the style of the host language.

If you binding Lua to a host written in C++, and the host has got style of `Camel Case`, so it's better that your Lua code use the `Camel Case`, the same with `snake_case`.

Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Jorge Visca
In reply to this post by Ross Berteig

On 06/06/17 20:15, Ross Berteig wrote:
> I've had my head stuffed in a book design task (using LuaLaTeX)
> recently. There really is good rational from book design for shorter
> line lengths based on studies of readability of running text. Printers
> (the people who handle lead type and spill ink on things) have known
> this intuitively about as long as moveable type has existed. The rule
> of thumb is that lines of print should be perhaps 45 to 75 characters
> long to avoid tracking to the wrong line as one reads. Mitigating that
> in code, you have the varying indentation, but generally keeping the
> ink to 66 characters more or less is likely easier on the reader.

I read code very differently than books, so I don't think that rationale
translates well. Wen reading book one reads "horizontally", in the sense
that you don't go to the next line until you've reached the end of the
current.

In code, there's both horizontal and vertical reading. It's pretty
common to read a piece of code only reading the first word/few words
across multiple lines. For example, just reading the names of the
functions being called, the variables being updated, or how the
iterators are nested, and only caring about their order and not the
exact parameters (they're obvious) nor the assigned expressions (you do
not understand them anyway :)). This kind of "vertical" reading can be
repeated once and again until I understand what's going on.

So, the vertical structure is at least as important, probably more, as
the horizontal. I usually will gladly compromise on the horizontal
legibility for the sake of the vertical one, because I spend a lot of
time scrolling trough code.

Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

KHMan
In reply to this post by Daurnimator
On 6/8/2017 11:50 AM, Daurnimator wrote:
> On 7 June 2017 at 01:41, Russell Haley wrote:
>> I am biased, but I find daurnimators code so elegantly simple it 'has no style'.

Learn the principle, abide by the principle,
and dissolve the principle.*
                                 -- Bruce Lee

> Thanks!
> I wouldn't say it has no style though: my coding style has evolved
> over the years.
> Back in 2008ish I wrote this up about my coding style at the time:
> https://code.google.com/archive/p/lomp/wikis/CodingStyle.wiki
> However much of my preferences have now changed.
>
> If I thought anyone would read+follow a coding style guide, I might
> keep one updated. But I've learnt that no one *does* read them: it's
> more practical to have a "house style" for a project, and catch
> anything that deviates in a pull request.
> The only time a guide works is when they have tooling to enforce it:
> however for such a tool to be useful (no one agrees on style!) it has
> to be tremendously configurable.
> Even then you have to persuade people to use the tooling (see how
> often people use astyle or clang-format).

* https://en.wikiquote.org/wiki/Bruce_Lee
His books are of course better than a page of quotes. Roughly:
First, you learn the forms. Then you master, or internalize the
forms. Finally, you break free of the forms when you see fit.

--
Cheers,
Kein-Hong Man (esq.)
Selangor, Malaysia


Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Sean Conner
In reply to this post by Jorge Eduardo
It was thus said that the Great Edu Araújo once stated:
> Why do not we agree on an official style guide for the Lua language?
> Something that improves the readability of the code, like PEP-8 for Python?

  The only way to enforce an official style in *any* language is to embed
the style in the language definition itself.  No even the creators of Go
were that fascist in their zeal for an official coding style (they wimped
out and created go-fmt).

  -spc (I'm being half-serious here, by the way ... )


Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Russell Haley
In reply to this post by Daurnimator
On Wed, Jun 7, 2017 at 8:50 PM, Daurnimator <[hidden email]> wrote:
> On 7 June 2017 at 01:41, Russell Haley <[hidden email]> wrote:
>> I am biased, but I find daurnimators code so elegantly simple it 'has no style'.
>
> Thanks!
> I wouldn't say it has no style though: my coding style has evolved
> over the years.
> Back in 2008ish I wrote this up about my coding style at the time:
> https://code.google.com/archive/p/lomp/wikis/CodingStyle.wiki
> However much of my preferences have now changed.

Well apparently I do have a style and I Bruce-Lee'd it from daurnimator. :P

Russ

> If I thought anyone would read+follow a coding style guide, I might
> keep one updated. But I've learnt that no one *does* read them: it's
> more practical to have a "house style" for a project, and catch
> anything that deviates in a pull request.
> The only time a guide works is when they have tooling to enforce it:
> however for such a tool to be useful (no one agrees on style!) it has
> to be tremendously configurable.
> Even then you have to persuade people to use the tooling (see how
> often people use astyle or clang-format).
>

Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Russell Haley
In reply to this post by Russell Haley
On Tue, Jun 6, 2017 at 2:51 PM, Russell Haley <[hidden email]> wrote:

> On Tue, Jun 6, 2017 at 10:03 AM, Sean Conner <[hidden email]> wrote:
>> It was thus said that the Great Russell Haley once stated:
>>> Sorry for the top post.
>>>
>>> Oh, and twenty indents? The version of Lua I use has a keyword called
>>> 'function'. And adhering to 80 columns is just silly. It was silly 20
>>> years ago when I started writing code.
>>
>>   But where's the cutoff?  I have some XSLT code [1] where some of the lines
>> are long.  Really long.  Like 250 characters long:
>>
>>   <xsl:param name="image"><xsl:value-of select="/site/section[@id='About']/subsection[position()=1]/page[position()=1]/@filename"/>.<xsl:value-of select="/site/section[@id='About']/subsection[position()=1]/page[position()=1]/img/@type"/></xsl:param>
>>
>> (note the two character indent)
>>
>>   This is, in my opinion, a bit too long (but if broken up, would be a real
>> mess and would probably mess up the output too much).
>>
>>   I find 80 to be nice---I can fit several xterms side by side when
>> programming (on my monitor at work---five side by side).
>>
>>   -spc (It's not a hard rule wit me, but a guideline I try to follow)
>>
>> [1]     I was playing around with it about fifteen years ago and decided to
>>         convert my site [2] to XML, and use XSLT to convert it to HTML (and
>>         to generate all links between pages and sections)
>>
>> [2]     http://www.conman.org/
>
> My preference is to maximize the amount of information on a single
> screen. While 250 characters is very long, picking an arbitrary number
> of characters applicable to computing in 1981 is suboptimal. Your
> example of multiple xterms is one good reason to keep lines short, but
> I can also easily put two windows at 150 characters side by side on a
> reasonable modern monitor. After looking at some of my code, it seems
> my lua lines are very short and my C# lines can get up to about 140
> characters. Either way, I try to be descriptive rather than
> restrictive in my code style. That means longer variable names and
> sometimes putting everything on one line if it makes sense. One of my
> current favorites in Lua is if/then/else on one line, which will
> rarely fit in 80 characters:
>
> if table.value == "another value" then number1 = number1 + 6 else
> number1 = 0 end
>
> (admittedly that looks much nicer in ZeroBrane with color coding).
>
> Russ

Here's some Powershell code from my installer. I don't use toolbars in
the Powershell Integrated Script Environment (ISE), so my lines get
monsterously long. I'd probably re-factor it if I was expecting anyone
else to use it, but why not maximize your screen? Screens are HUGE now
(yes, I know, not everyone has a bigillion megapixel yadda yadda).

https://github.com/RussellHaley/PUC-Lua-Installer/blob/master/templates/pli-tools.ps1#L126

I think this makes the code far more readable. I can compare all the
variables and ensure uniformity.

Russ

Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Hisham
In reply to this post by Pierre Chapuis
On 7 June 2017 at 04:47, Pierre Chapuis <[hidden email]> wrote:

> June 6, 2017 11:32 PM, "Hisham" <[hidden email]> wrote:
>
>> And here's another Style Guide added to the list, taking input from
>> the ones posted in this thread, and adjusting them to the style guide
>> as used in the LuaRocks codebase. Enjoy!
>>
>> https://github.com/luarocks/lua-style-guide
>
> Since everyone is posting theirs I decided I'd post
> the guidelines used at my company for reference too:
>
> https://gist.github.com/catwell/b3c01dbea413aa78675740546dfd5ce2

Thank you for sharing! I used it as a source of more items to add to
the LuaRocks Style Guide (added new "function calls" and "errors"
sections, and some additions to the "modules" section, all of which
mostly match your recommendations, and a new section on "static
checking" recommending luacheck as well but explaining why I skip some
luacheck warnings).

-- Hisham

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

steve donovan
In reply to this post by Sean Conner
On Thu, Jun 8, 2017 at 7:21 AM, Sean Conner <[hidden email]> wrote:
>  The only way to enforce an official style in *any* language is to embed
> the style in the language definition itself.  No even the creators of Go
> were that fascist in their zeal for an official coding style (they wimped
> out and created go-fmt).

Heh, but they had curly-braces to deal with, always a fine topic for
bikeshedding!

We do not have the brace problem, fortunately, just the need to indent
(which Python embeds in the language)

As for 'programs are readable documents', they always look to be
better as poetry, not prose; never fear using too much vertical space.

The Rust compiler by default spits out yellow ink if violations of the
naming style happen (CamelCase types, snake_case variables, SHOUTING
constants)

I'm fine with that since my opinions do not differ from rustc ;)

>
>   -spc (I'm being half-serious here, by the way ... )
>
>

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Dirk Laurie-2
2017-06-08 13:51 GMT+02:00 steve donovan <[hidden email]>:

> Heh, but they had curly-braces to deal with, always a fine topic for
> bikeshedding!

Finally, the word emerges. I have been restraining myself, disciplining
my fingers, choking it down, ever since this thread started, and there
you go and just casually spit it out.

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Sean Conner
In reply to this post by steve donovan
It was thus said that the Great steve donovan once stated:

> On Thu, Jun 8, 2017 at 7:21 AM, Sean Conner <[hidden email]> wrote:
> >  The only way to enforce an official style in *any* language is to embed
> > the style in the language definition itself.  No even the creators of Go
> > were that fascist in their zeal for an official coding style (they wimped
> > out and created go-fmt).
>
> Heh, but they had curly-braces to deal with, always a fine topic for
> bikeshedding!
>
> We do not have the brace problem, fortunately, just the need to indent
> (which Python embeds in the language)
>
> As for 'programs are readable documents', they always look to be
> better as poetry, not prose; never fear using too much vertical space.
>
> The Rust compiler by default spits out yellow ink if violations of the
> naming style happen (CamelCase types, snake_case variables, SHOUTING
> constants)
>
> I'm fine with that since my opinions do not differ from rustc ;)

  Sigh.  A reason not to use Rust then.

  -spc (IHateCamelCase)


Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Tim Hill
In reply to this post by Sean Conner

> On Jun 5, 2017, at 3:38 PM, Sean Conner <[hidden email]> wrote:
>
>
> * Prefer function syntax over variable syntax.  This helps differentiate
> between named and anonymous functions [Oooh!  A rational!  Unfortunately,
> this is rare in the document]
>

This one particularly bugs me, as it creates an idea in the heads of developers that there is some kind of subtle semantic distinction which does not exist. And I agree that there is very little rationalization here at all.

—Tim



Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Tim Hill
In reply to this post by steve donovan

> On Jun 6, 2017, at 12:13 AM, steve donovan <[hidden email]> wrote:
>
> On Mon, Jun 5, 2017 at 6:52 PM, Pierre Chapuis <[hidden email]> wrote:
>> [1] https://github.com/Olivine-Labs/lua-style-guide
>
> "Using four spaces or tabs will result in public flogging". Ouch!
>
> Reminds me of when Mike Pall said he would never collaborate with
> anyone who used three-space indents.
>
> Sean has it, I think: there's really not enough rationale for these
> arbitrary things. I would go with Roberto, I don't think he would flog
> anyone for using four spaces.
>

I’ve used 4 spaces now mostly because my eyesight is poor and it simply helps me see things more clearly. It’s also so common as the default tab for editors that I prefer just going with the flow rather than always fighting other team members and/or other language standards in multi-language projects.

—Tim


Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Russell Haley
It would be interesting to put these lists of rules that people have
generated in a system that records votes and see what the real
community opinion of them is. Also, if it collected the list of items
you agreed with (and a converse list as well) and then compared that
to other peoples lists, you might be able to get a really good picture
of peoples various styles.

On Thu, Jun 8, 2017 at 3:58 PM, Tim Hill <[hidden email]> wrote:

>
>> On Jun 6, 2017, at 12:13 AM, steve donovan <[hidden email]> wrote:
>>
>> On Mon, Jun 5, 2017 at 6:52 PM, Pierre Chapuis <[hidden email]> wrote:
>>> [1] https://github.com/Olivine-Labs/lua-style-guide
>>
>> "Using four spaces or tabs will result in public flogging". Ouch!
>>
>> Reminds me of when Mike Pall said he would never collaborate with
>> anyone who used three-space indents.
>>
>> Sean has it, I think: there's really not enough rationale for these
>> arbitrary things. I would go with Roberto, I don't think he would flog
>> anyone for using four spaces.
>>
>
> I’ve used 4 spaces now mostly because my eyesight is poor and it simply helps me see things more clearly. It’s also so common as the default tab for editors that I prefer just going with the flow rather than always fighting other team members and/or other language standards in multi-language projects.
>
> —Tim
>
>

Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Charles Heywood
It would be easy to make a Google form to record answers with.

On Fri, Jun 9, 2017, 13:43 Russell Haley <[hidden email]> wrote:
It would be interesting to put these lists of rules that people have
generated in a system that records votes and see what the real
community opinion of them is. Also, if it collected the list of items
you agreed with (and a converse list as well) and then compared that
to other peoples lists, you might be able to get a really good picture
of peoples various styles.

On Thu, Jun 8, 2017 at 3:58 PM, Tim Hill <[hidden email]> wrote:
>
>> On Jun 6, 2017, at 12:13 AM, steve donovan <[hidden email]> wrote:
>>
>> On Mon, Jun 5, 2017 at 6:52 PM, Pierre Chapuis <[hidden email]> wrote:
>>> [1] https://github.com/Olivine-Labs/lua-style-guide
>>
>> "Using four spaces or tabs will result in public flogging". Ouch!
>>
>> Reminds me of when Mike Pall said he would never collaborate with
>> anyone who used three-space indents.
>>
>> Sean has it, I think: there's really not enough rationale for these
>> arbitrary things. I would go with Roberto, I don't think he would flog
>> anyone for using four spaces.
>>
>
> I’ve used 4 spaces now mostly because my eyesight is poor and it simply helps me see things more clearly. It’s also so common as the default tab for editors that I prefer just going with the flow rather than always fighting other team members and/or other language standards in multi-language projects.
>
> —Tim
>
>

--
--

Software Developer / System Administrator
Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Hisham
In reply to this post by Russell Haley
Design by voting hardly ever works, especially when there is
aesthetics involved. Some of these choices are related to each other,
so a hodgepodge of "most voted options" would likely be inconsistent.
Not to mention that lua-l is just a slice of the Lua world as a whole
(and those who voice their opinions here are a further slice of that),
so it's hard to represent that as the community opinion too. In any
case, the styles presented here already display some combinations
which work well for different people, so I think that's pretty good to
get people going when defining their own.

-- Hisham

On 9 June 2017 at 15:42, Russell Haley <[hidden email]> wrote:

> It would be interesting to put these lists of rules that people have
> generated in a system that records votes and see what the real
> community opinion of them is. Also, if it collected the list of items
> you agreed with (and a converse list as well) and then compared that
> to other peoples lists, you might be able to get a really good picture
> of peoples various styles.
>
> On Thu, Jun 8, 2017 at 3:58 PM, Tim Hill <[hidden email]> wrote:
>>
>>> On Jun 6, 2017, at 12:13 AM, steve donovan <[hidden email]> wrote:
>>>
>>> On Mon, Jun 5, 2017 at 6:52 PM, Pierre Chapuis <[hidden email]> wrote:
>>>> [1] https://github.com/Olivine-Labs/lua-style-guide
>>>
>>> "Using four spaces or tabs will result in public flogging". Ouch!
>>>
>>> Reminds me of when Mike Pall said he would never collaborate with
>>> anyone who used three-space indents.
>>>
>>> Sean has it, I think: there's really not enough rationale for these
>>> arbitrary things. I would go with Roberto, I don't think he would flog
>>> anyone for using four spaces.
>>>
>>
>> I’ve used 4 spaces now mostly because my eyesight is poor and it simply helps me see things more clearly. It’s also so common as the default tab for editors that I prefer just going with the flow rather than always fighting other team members and/or other language standards in multi-language projects.
>>
>> —Tim
>>
>>
>

12345