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 ?

Russell Haley
Sorry for the top post.

I find a style guides ineffective for organizations larger than one developer.

More than any other language I have used, I find that each lua solution seems to have its own natural flow. The problem set almost defines the code style.

I've tried lots of styles over the last year or two and each time Lua manages to bust my pattern. Yes, obviously my patterns weren't great, but my point to Joe is this: you already did the right thing by reading code. Read lots and lots of people's code and you will soon learn what is effective in Lua. 

I am biased, but I find daurnimators code so elegantly simple it 'has no style'. 

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. 

Fwiw
Russ

Sent from my BlackBerry 10 smartphone on the Virgin Mobile network.
  Original Message  
From: Dirk Laurie
Sent: Tuesday, June 6, 2017 7:12 AM
To: Lua mailing list
Reply To: Lua mailing list
Subject: Re: Lua Style Guide ?

2017-06-06 15:25 GMT+02:00 Marc Balmer <[hidden email]>:
> Tabs are holy. Spaces, no matter how many, are just a cheap substitute.
>
> Any yes, any line shall never exceed 80 characters, that's the eleventh
> commandment!

WIth great respect to all those who are gleefully enjoying the direction
this thread is going, a quotation from the Bible [1]:

Whitespace of whitespaces, saith the Programmer; all is whitespace.

After all, Lua is whitespace-agnostic; you can just pass your chunk
of code to quite a simple reformatter [2].

Style is much more than that.

It deals with questions such as:

- Do you explicitly code 'nil' in situations where it will be supplied
by default?
- Do you write "y=10*x" or "y=10.0*x" when you know that x is
floating-point?
- Do you monkeypatch globals?
- Do you use closures to encapsulate upvalues?

[1] Modern Geek Version.
[2] Any idiot can write one.[3] My first Lua program (part of my LuaTeX
primer) was just such a reformatter.
[3] Not necessarily a good one. My first Lua program can't reformat
itself (failure to take into account the "--[^\n]*\n" comment construction).


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 Tue, Jun 6, 2017 at 2:32 PM, Pierre Chapuis <[hidden email]> wrote:
> > I think style guide are important at company- or project- level: you
> > typically don't want mixed styles in your code base.
>
> Yes, that's part of being a professional and fitting in with everyone.
>
> > At community level I don't care about this. If we could all agree on
> > things that matter even when you don't look at the code (e.g. usage
> > of globals in modules, etc) I would be happy.
>
> Ditto and likewise! Some things are not a good idea, and there are
> tools which can identify these.
>
> I once had to use Pylint, and I've never come across a more
> opinionated piece of software, ever. And the real problems were
> happily buried in the style advice noise.

  Fortunately, LuaCheck isn't *that* opinionated (it will complain about
lines longer than 120 characters and blank lines with spaces) and what it
*is* opinionated about can be ignored (either through a config file or via
special comments in the code itself).

  -spc (Who has found real bugs in his code through using LuaCheck)

Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Soni "They/Them" L.
In reply to this post by Dirk Laurie-2


On 2017-06-06 11:11 AM, Dirk Laurie wrote:

> 2017-06-06 15:25 GMT+02:00 Marc Balmer <[hidden email]>:
>> Tabs are holy.  Spaces, no matter how many, are just a cheap substitute.
>>
>> Any yes, any line shall never exceed 80 characters, that's the eleventh
>> commandment!
> WIth great respect to all those who are gleefully enjoying the direction
> this thread is going, a quotation from the Bible [1]:
>
>    Whitespace of whitespaces, saith the Programmer; all is whitespace.
>
> After all, Lua is whitespace-agnostic; you can just pass your chunk
> of code to quite a simple reformatter [2].
>
> Style is much more than that.
>
> It deals with questions such as:
>
> - Do you explicitly code 'nil' in situations where it will be supplied
> by default?
> - Do you write "y=10*x" or "y=10.0*x" when you know that x is
> floating-point?
> - Do you monkeypatch globals?
> - Do you use closures to encapsulate upvalues?
>
> [1] Modern Geek Version.
> [2] Any idiot can write one.[3] My first Lua program (part of my LuaTeX
> primer) was just such a reformatter.
> [3] Not necessarily a good one. My first Lua program can't reformat
> itself (failure to take into account the "--[^\n]*\n" comment construction).
>

I mean I guess one could argue for line-feed indentation...

--
local function x(a)

local function y(b)


return a+b

end

return y
end
--

Just remember to use a portrait monitor. Benefits include you can still
use the full 80col per line, and you have more vertical space than
horizontal space in portrait mode.

--
Disclaimer: these emails may be made public at any given time, with or without reason. If you don't agree with this, DO NOT REPLY.


Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

nobody
In reply to this post by Sean Conner
On 06/06/2017 12:38 AM, Sean Conner wrote:
> [1] I may allow such use for single use functions for modules, but
> then again, I do modules a bit differently [2] to maintain easy
> compatability with Lua 5.1.
>
> [2] Check out
> https://github.com/spc476/lua-conmanorg/blob/master/lua/date.lua for
>  an example.

On modules / globals:  This is an important aspect of code style &
organization that has a big impact on how you can interact with the code
and is hard to change later.  Most common styles rely heavily on
`local`s / upvalues, which (IMHO) negatively impacts debuggability &
flexibility.

As an example, let's say you have public `foo.unparse`, which uses
(among many others) internal `readDateTime` which uses internal
`readTime` (which happens to contain an arithmetic bug – it returns
slightly wrong values of the right type, so there's no nice stack
trace).  Your tests tell you that `unparse` gives wrong results.  Among
the dozens of internal functions, how do you localize the bug?

To test the pieces – the internal functions – (whether by test scripts
or in the REPL) you can (temporarily) edit the source and either put
your test code in there (so no REPL for you) or remove the `local`
annotations (yuck!), or you traverse the chain of upvalues.  If you add
metatable magic on functions' `__index`, this can be as "nice" as
`foo.unparse.readDateTime.readTime`, otherwise it may be as terrible as
select(2,debug.getupvalue(select(2,debug.getupvalue(foo.unparse,1)),2)).
Both are brittle: Code changes may change the path you have to take, you
often have to traverse several levels of upvalues, …  I can't think of a
better way to access the parts (and I don't think there is one…)

How do people using these module styles deal with that?  Is it actually
a problem or are you (e.g.) using a completely different debugging
approach?  (How/) Do you test internal functions?  (How/) Do you REPL?



I try to avoid the problem by giving each module its own module
environment (separate from the module table), usually starting modules
with (5.1-5.3 compatible)

   local _ENV = setmetatable( { _M = { } }, { __index = _ENV or _G } )
   if setfenv then  setfenv( 1, _ENV )  end
   _M._MENV, package.loaded[...] = _ENV, _M

(_M is the module table, expose stuff by adding to _M.  _ENV / _M._MENV
is the module environment and __index-es into the parent environment.
Don't `local` by default, put stuff in the module environment.  You can
additionally `local` for speed where needed, as in `foo = …; local foo =
foo` or `local foo = …; _ENV.foo = foo`.)

This avoids both the problem of accidental non-`local`s becoming global
or public and makes the environment easily accessible for debugging.
(If you prefer, omit the `_M._MENV = _ENV` and `debug.getupvalue` the
environment (once, from (almost) any exposed function) for debugging.)

(Manually setting `package.loaded[modname]` is another thing that I see
rarely.  If you do this, you don't have to return the module at the end
– which means all module management happens in one place (at the top),
not two (top and bottom).  It also permits module "foo" to `require
"foo.bar"`, which can then `require "foo"`, without spinning in a
require-loop.)

Another nice property is that submodules can share their environment –
e.g. in "foo.bar" start instead with `local _ENV = require "foo"._MENV`.
(This is really nice for "util" modules – they can simply populate the
module environment and don't have to add a contrived dummy package.
It's also much easier to split a single module's implementation across
several files.  Etc. pp. – with this style/approach, the module
environment is not just a bunch of scattered upvalues, it's an actual
environment/table that can easily be queried/manipulated/…)

-- nobody

Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Sean Conner
In reply to this post by Russell Haley
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/

Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

J Doe
In reply to this post by nobody
Hi everyone,

WOW!  I did not expect so many online sources to check as well as useful opinions on those sources.  I am working through your responses (I count 23 messages, at the moment!), but thank you very much to everyone who contributed - I value your insight as I'm a newer (2 months), user of Lua.

Also - wanted to put out an apology for posting the same message 3 times.  When I posted the original message, I did not hear back from Mailman.  I did some SMTP debugging and found that I wasn't having trouble posting my messages from my end, but I didn't realize the Lua list was queuing my resends over the last couple of days.

- J

Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

steve donovan
In reply to this post by Sean Conner
On Tue, Jun 6, 2017 at 5:45 PM, Sean Conner <[hidden email]> wrote:
>   Fortunately, LuaCheck isn't *that* opinionated (it will complain about
> lines longer than 120 characters and blank lines with spaces) and what it
> *is* opinionated about can be ignored (either through a config file or via
> special comments in the code itself).

These are reasonable complaints ;)

And yes, I find bugs in my code with static testing as well, although
(being a cat) I did my own. So it embeds my opinions.  (One reason why
wheel-rewriting is so bracing and fun)

Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Hisham
In reply to this post by J Doe
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

-- Hisham


On 6 June 2017 at 14:05, J Doe <[hidden email]> wrote:
> Hi everyone,
>
> WOW!  I did not expect so many online sources to check as well as useful opinions on those sources.  I am working through your responses (I count 23 messages, at the moment!), but thank you very much to everyone who contributed - I value your insight as I'm a newer (2 months), user of Lua.
>
> Also - wanted to put out an apology for posting the same message 3 times.  When I posted the original message, I did not hear back from Mailman.  I did some SMTP debugging and found that I wasn't having trouble posting my messages from my end, but I didn't realize the Lua list was queuing my resends over the last couple of days.
>
> - J
>

Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Russell Haley
In reply to this post by Sean Conner
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

Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Russell Haley
In reply to this post by Hisham
On Tue, Jun 6, 2017 at 2:27 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
>
> -- Hisham

https://github.com/luarocks/lua-style-guide#line-lengths

Rationale: No one works on VT100 terminals anymore. If line lengths
are a proxy for code complexity, we should address code complexity
instead of using line breaks to fit mind-bending statements over
multiple lines.

+1

Russ

Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Russell Haley
In reply to this post by Hisham
https://github.com/luarocks/lua-style-guide#modules

"Rationale: C is much harder to read if we have to keep going back to
the top to check how you chose to call a module."

Was this meant to say C or Lua?

Russ

On Tue, Jun 6, 2017 at 2:27 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
>
> -- Hisham
>
>
> On 6 June 2017 at 14:05, J Doe <[hidden email]> wrote:
>> Hi everyone,
>>
>> WOW!  I did not expect so many online sources to check as well as useful opinions on those sources.  I am working through your responses (I count 23 messages, at the moment!), but thank you very much to everyone who contributed - I value your insight as I'm a newer (2 months), user of Lua.
>>
>> Also - wanted to put out an apology for posting the same message 3 times.  When I posted the original message, I did not hear back from Mailman.  I did some SMTP debugging and found that I wasn't having trouble posting my messages from my end, but I didn't realize the Lua list was queuing my resends over the last couple of days.
>>
>> - J
>>
>

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Russell Haley
In reply to this post by Roland
On Mon, Jun 5, 2017 at 1:17 PM, Roland Yonaba <[hidden email]> wrote:

> Hi Doe,
>
> I am not aware of any official style guide for Lua. However, there are a
> fair common set of rules that Lua people tend to use and advocate. You can
> find them at:
>
> - Lua Users Style Guide: http://lua-users.org/wiki/LuaStyleGuide
> - Olivine's Lua Style Guide: https://github.com/Olivine-Labs/lua-style-guide
>
> I also recently came across these :
> - Zaki's https://github.com/zaki/lua-style-guide
> - Ykst's fork: https://github.com/ykst/lua-style-guide
>
> Hope these links help.
>
> Regards,
> Roland.

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:

for k, _ in pairs(tbl) do
--do something with key and not the value
end

Can I ask where you got that syntax from? I ask out of curiosity (and
potential adoption) as it does seem to make your code very
understandable. Any other comments on '_' as a variable name?

Russ

>
>> From: J Doe <[hidden email]>
>> Subject: Lua style guide ?
>
>
>>
>> Hi,
>>
>> I was wondering if there is an official or commonly accepted style guide
>> for Lua ?  I have adopted the same style as Roberto while working through
>> the 3rd and 4th edition of "Programming Lua", but I was wondering if there
>> is an actual written or community followed standard (similar to how Python
>> has PEP-8) ?
>>
>> Thanks,
>>
>> - J
>>
>>
>>
>>
>> ------------------------------
>>
>> Message: 2
>> Date: Fri, 2 Jun 2017 16:38:11 -0400
>> From: J Doe <[hidden email]>
>> Subject: Style guide for Lua ?
>> To: Lua List <[hidden email]>
>> Message-ID: <[hidden email]>
>> Content-Type: text/plain;       charset=us-ascii
>>
>>
>> Hi,
>>
>> I was wondering if there is an official or commonly accepted style guide
>> for Lua ?  I have adopted the same style as Roberto while working through
>> the 3rd and 4th edition of "Programming Lua", but I was wondering if there
>> is an actual written or community followed standard (similar to how Python
>> has PEP-8) ?
>>
>> Thanks,
>>
>> - J
>>
>>
>>
>> ------------------------------
>>
>> _______________________________________________
>> lua-l mailing list
>> [hidden email]
>>
>> http://listmaster.pepperfish.net/cgi-bin/mailman/listinfo/lua-l-lists.lua.org
>>
>>
>> End of lua-l Digest, Vol 83, Issue 4
>> ************************************
>
>

Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

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

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

  I found this bit of code I wrote [1]:

  window.events =
  {
    -- Some other methods snipped

    Expose = function(event)
      if event.count == 0 then
        event.window:copy_area(
                  background,
                  gc,
                  background.width,
                  background.height,
                  math.floor((384 - background.width) / 2),
                  400
          )
        event.window:copy_area(
                  church,
                  gc,
                  church.width,
                  church.height,
                  0,
                  0
          )
      end
    end,
  }

  The functions tend to require a large number of parameters [3] (hey, blame
the designers of Xlib) and thusly, I came to this style of formatting for
calling such functions.  Otherwise, the code would look like:

  window.events =
  {
    -- Some other methods snipped

    Expose = function(event)
      if event.count == 0 then
        event.window:copy_area(background,gc,background.width,background.height,math.floor((384 - background.width) / 2),400)
        event.window:copy_area(church,gc,church.width,church.height,0,0)
      end
    end,
  }

which I personally find hard to read.  Also, as several of the functions
require tables, that style also tends to fall out:

        local function refresh_win_over()
          display:send_event(
                'ExposureMask',
                {
                  type   = 'Expose',
                  window = window,
                  x      = 0,
                  y      = 0,
                  width  = window.width * 16,
                  height = window.height * 16,
                }
          )
          display:send_event(
                'ExposureMask',
                {
                  type   = 'Expose',
                  window = overview,
                  x      = 0,
                  y      = 0,
                  width  = OS * land.WIDTH,
                  height = OS * land.HEIGHT
                }
          )
        end

  This also brings up another style convention I use---the use of "" or ''
for strings.  I tend to use "" for strings that will be displayed to the
user, and '' for strings that are used as enum type data, such as
'ExposureMask' or 'Expose' here.  You can also see my preference for
vertical alignment (again, I find it easier to read and is a hold over from
my days as an assembly language programmer).

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

  I'd write that out on several lines:

        if table.value == 'another value' then
          number1 = number1 + 6
        else
          number1 = 0
        end

  But that's me.

  -spc

[1] It uses a module I wrote that wraps Xlib.  I have no immediate plans
        to release this because 1) it requires you know Xlib to actually use
        it and 2) it uses TCC [2], which is a bit touchy to use.

[2] Tiny C-Compiler---a C compiler that is also a library you can link
        into an application if you want to compile C code on the fly [4].

[3] There are actually 8 parameters required for copy_area().  You see
        six specified; the seventh is the implicit window parameter (via the
        object call syntax) and the eight is an upvalue containing the
        current display.

[4] Don't even ask what I need this for.

Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Russell Haley
On Tue, Jun 6, 2017 at 3:23 PM, Sean Conner <[hidden email]> wrote:

> It was thus said that the Great Russell Haley once stated:
>> 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.
>
>   I found this bit of code I wrote [1]:
>
>   window.events =
>   {
>     -- Some other methods snipped
>
>     Expose = function(event)
>       if event.count == 0 then
>         event.window:copy_area(
>                   background,
>                   gc,
>                   background.width,
>                   background.height,
>                   math.floor((384 - background.width) / 2),
>                   400
>           )
>         event.window:copy_area(
>                   church,
>                   gc,
>                   church.width,
>                   church.height,
>                   0,
>                   0
>           )
>       end
>     end,
>   }
>
>   The functions tend to require a large number of parameters [3] (hey, blame
> the designers of Xlib) and thusly, I came to this style of formatting for
> calling such functions.  Otherwise, the code would look like:
>
>   window.events =
>   {
>     -- Some other methods snipped
>
>     Expose = function(event)
>       if event.count == 0 then
>         event.window:copy_area(background,gc,background.width,background.height,math.floor((384 - background.width) / 2),400)
>         event.window:copy_area(church,gc,church.width,church.height,0,0)
>       end
>     end,
>   }
>
> which I personally find hard to read.  Also, as several of the functions
> require tables, that style also tends to fall out:
>
>         local function refresh_win_over()
>           display:send_event(
>                 'ExposureMask',
>                 {
>                   type   = 'Expose',
>                   window = window,
>                   x      = 0,
>                   y      = 0,
>                   width  = window.width * 16,
>                   height = window.height * 16,
>                 }
>           )
>           display:send_event(
>                 'ExposureMask',
>                 {
>                   type   = 'Expose',
>                   window = overview,
>                   x      = 0,
>                   y      = 0,
>                   width  = OS * land.WIDTH,
>                   height = OS * land.HEIGHT
>                 }
>           )
>         end
>
>   This also brings up another style convention I use---the use of "" or ''
> for strings.  I tend to use "" for strings that will be displayed to the
> user, and '' for strings that are used as enum type data, such as
> 'ExposureMask' or 'Expose' here.  You can also see my preference for
> vertical alignment (again, I find it easier to read and is a hold over from
> my days as an assembly language programmer).
>
>> 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).
>
>   I'd write that out on several lines:
>
>         if table.value == 'another value' then
>           number1 = number1 + 6
>         else
>           number1 = 0
>         end
>
>   But that's me.

Looking back at that statement I probably would have refactored it
too. I know I had done this a few times but couldn't find any
instances in my Github repos, so maybe I've changed my mind on that (I
program late at night and often don't remember what I did)? Damn, now
I'm going to have to go and re-write my style guide. ;)

>   -spc
>
> [1]     It uses a module I wrote that wraps Xlib.  I have no immediate plans
>         to release this because 1) it requires you know Xlib to actually use
>         it and 2) it uses TCC [2], which is a bit touchy to use.
>
> [2]     Tiny C-Compiler---a C compiler that is also a library you can link
>         into an application if you want to compile C code on the fly [4].
>
> [3]     There are actually 8 parameters required for copy_area().  You see
>         six specified; the seventh is the implicit window parameter (via the
>         object call syntax) and the eight is an upvalue containing the
>         current display.
>
> [4]     Don't even ask what I need this for.

All said, an absolutely reasonable approach. However, I like single
blocks of logic (i.e. a function call) on one line:

log = assert(rolling_logger(conf.debug_file_name, conf.file_roll_size
or 1024*1024*10, conf.max_log_files or 31)).

That way I can scan the left side of the screen for hints as to the
logic I am looking for and only read the function if required.

Adding values to table is a mixed bag in my code. If the assignments
are syntactically small and all fit on one line, I tend to do that.
Otherwise I split it as you have.

Anyway, here is my point: We have a C/C++/C# style guide at work and
nobody uses it. Even the people that wrote it break the rules all the
time. That's because (IMHO) style guides are pedantic and serve little
value other than broad brush strokes. Readability is very very
subjective. At work we call it the style guide the "Developers
Handbook" and it should be tossed in the garbage because it does
NOTHING for consistence[1]. We have some C# code that is particularly
unreadable because myself and the other developer used different
styles. The mess was more my fault then his because I should have
stuck with the "other" style when re-coding to keep it logically
consistent. Instead, I insisted on using the Handbook styling and now
it's a mess. I think a FAR better approach to consistent coding in an
organization is to focus on logical consistency. Some of the rules in
the style guide that Muhammad presented lean in that direction and
server far more practical use.  I believe that logical patterns are
more valuable then syntactic patterns and people tend to get caught on
the latter.

[1] - If you are denoting logic via a syntactical style, then I think
there is value, like in the case of CamelCase for class names.
However, that's not really a 'style', it's a coding pattern.


Fwiw,

Russ

Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Andrew Starks-2
In reply to this post by steve donovan

On Tue, Jun 6, 2017 at 12:13 steve donovan <[hidden email]> wrote:
On Tue, Jun 6, 2017 at 5:45 PM, Sean Conner <[hidden email]> wrote:
>   Fortunately, LuaCheck isn't *that* opinionated (it will complain about
> lines longer than 120 characters and blank lines with spaces) and what it
> *is* opinionated about can be ignored (either through a config file or via
> special comments in the code itself).

These are reasonable complaints ;)

And yes, I find bugs in my code with static testing as well, although
(being a cat) I did my own. So it embeds my opinions.  (One reason why
wheel-rewriting is so bracing and fun)

I like reading all of these opinions. It's fun on a summer day, while grilling...

Big, complex ideas require a process to develop, a language to communicate them and a structure to hold them together. Part of the art of the process is applying a thoughtful style to the presentation. 

I believe that the culture and practice of coding would be enhanced if it were imbued with more of that attitude. 

There is a technical problem to be solved. 

There is an art to solving it and in expressing its solution. Part of that art is style, which if done well, can contribute a great deal to its meaning. 

Hot headed opinions are super fun, though. So there's that[1]. 



-Andrew


[1] Rush is the greatest band ever. 
Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Ross Berteig
In reply to this post by Russell Haley


On 6/6/2017 2:58 PM, Russell Haley wrote:

> On Tue, Jun 6, 2017 at 2:27 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
>>
>> -- Hisham
> https://github.com/luarocks/lua-style-guide#line-lengths
>
> Rationale: No one works on VT100 terminals anymore. If line lengths
> are a proxy for code complexity, we should address code complexity
> instead of using line breaks to fit mind-bending statements over
> multiple lines.

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.

In an 80 column screen, a block of 66 characters leaves up to 14 spaces
for indentation. At 4 spaces per indent, you get three levels, at three
per you get four levels. I'm inclined to argue that if you needed five
levels you might have a problem that could benefit from some
refactoring. In the deeply nested loop cases where you can't refactor
that away, the loop body is likely expressible in less than 66 character
lines if you choose local variable names judiciously.

Of course, code is usually set in fixed-pitch fonts, which actually
makes tracking on long lines even more difficult.

Adding to that is the observation that at 10 chars/inch, an 80 column
screen fits within the printable borders of a letter-sized page (both US
letter and metric A4). Scatter in a few ASCII FF characters in front of
significant breaks in program flow, and listings become almost pleasant
to read.... (ok, I guess I'm old.)

--
Ross Berteig                               [hidden email]
Cheshire Engineering Corp.           http://www.CheshireEng.com/
+1 626 303 1602


Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Russell Haley
On Tue, Jun 6, 2017 at 4:15 PM, Ross Berteig <[hidden email]> wrote:

>
>
> On 6/6/2017 2:58 PM, Russell Haley wrote:
>>
>> On Tue, Jun 6, 2017 at 2:27 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
>>>
>>> -- Hisham
>>
>> https://github.com/luarocks/lua-style-guide#line-lengths
>>
>> Rationale: No one works on VT100 terminals anymore. If line lengths
>> are a proxy for code complexity, we should address code complexity
>> instead of using line breaks to fit mind-bending statements over
>> multiple lines.
>
>
> 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.

A rule I can see being useful on pages with blocks of uniform text.
However, my code is rarely uniform. I like my logic on one line if I
can sometimes. But there is no accounting for some taste. I also
prefer counting from 1.

Cheers,
Russ

> In an 80 column screen, a block of 66 characters leaves up to 14 spaces for
> indentation. At 4 spaces per indent, you get three levels, at three per you
> get four levels. I'm inclined to argue that if you needed five levels you
> might have a problem that could benefit from some refactoring. In the deeply
> nested loop cases where you can't refactor that away, the loop body is
> likely expressible in less than 66 character lines if you choose local
> variable names judiciously.
>
> Of course, code is usually set in fixed-pitch fonts, which actually makes
> tracking on long lines even more difficult.
>
> Adding to that is the observation that at 10 chars/inch, an 80 column screen
> fits within the printable borders of a letter-sized page (both US letter and
> metric A4). Scatter in a few ASCII FF characters in front of significant
> breaks in program flow, and listings become almost pleasant to read.... (ok,
> I guess I'm old.)
>
> --
> Ross Berteig                               [hidden email]
> Cheshire Engineering Corp.           http://www.CheshireEng.com/
> +1 626 303 1602
>
>

Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Pierre Chapuis
In reply to this post by Hisham
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

--
Pierre Chapuis

Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Pierre Chapuis
June 7, 2017 9:47 AM, "Pierre Chapuis" <[hidden email]> wrote:

> 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

... and I made an index of all those I saw posted here:

https://gist.github.com/catwell/af47d57611d9b2dd39b950190287105d

Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Roberto Ierusalimschy
In reply to this post by Russell Haley
> [...] 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

12345