Re: Lua Style Guide ?

[Russell Haley <russ.haley@...>]

On Tue, Jun 6, 2017 at 3:23 PM, Sean Conner <sean@conman.org> wrote:
> It was thus said that the Great Russell Haley once stated:
>> On Tue, Jun 6, 2017 at 10:03 AM, Sean Conner <sean@conman.org> 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