Styling parameter and variable types

[Daniele Sluijters]

With the future parser we can now add type annotations to a whole bunch of things. Usually it's pretty easy, just chuck the type in front of the variable and you're done. But what if you have multiple variables or class parameters beneath each other, do we align them, how do we align them, and what about more complex type definitions?

An example:

class test (

  String $param1,

  String $param2,

  Integer $param3,

  Variant[String, Integer] $param4 = 80,

  Struct[{ a => Enum[hi, there, everyone], b => Optional[Variant[Enum[yo, lo], Integer[2]]]}] $param5 = { a => 'hi', },

) {}

So do we style it like so: align based on starting token of required and option parameters

class test (

  String  $param1,

  String  $param2,

  Integer $param3,

  Variant[String, Integer]                                                                    $param4 = 80,

  Struct[{ a => Enum[hi, there, everyone], b => Optional[Variant[Enum[yo, lo], Integer[2]]]}] $param5 = { a => 'hi', },

) {}

Or do we take it one step further and align everything:

class test (

  String                                                                                      $param1,

  String                                                                                      $param2,

  Integer                                                                                     $param3,

  Variant[String, Integer]                                                                    $param4 = 80,

  Struct[{ a => Enum[hi, there, everyone], b => Optional[Variant[Enum[yo, lo], Integer[2]]]}] $param5 = { a => 'hi', },

) {}

Should we break up complex type definitions:

class test (

  String                           $param1,

  String                           $param2,

  Integer                          $param3,

  Variant[String, Integer]         $param4 = 80,

  Struct[{

    a => Enum[hi, there, everyone]

    b => Optional[Variant[

                    Enum[yo, lo],

                    Integer[2]]]

  }]                               $param5 = { a => 'hi', },

) {}

I like this last one best. It limits the length of the line and by splitting up the type definition according to the type we're defining (a hash) it becomes fairly easy for a human to parse. But then, should the Variant after the Optional be on a new line already or only the arguments to Variant since that one can take multiples (like in the way you'd break up an array over multiple lines) etc. etc. etc. I'm still not entirely happy about all the white spacing between the type and the actual variable name but I do like the columnar view it creates.

Eventually we'll be able to create/alias our own types which should limit the amount of crazy before a variable or parameter definition but until then, what do we do? And once we have the ability to create/alias our own types, how do we style those?

We don't have to agree on a "it must be done exactly this anal way" but a loose consensus about what it could look like would be useful.

[Martin Alfke]

Hi Daniele,

many thanks for bringing up the Type style question.

On 10 Dec 2014, at 14:23, Daniele Sluijters <daniele....@gmail.com> wrote:

> With the future parser we can now add type annotations to a whole bunch of things. Usually it's pretty easy, just chuck the type in front of the variable and you're done. But what if you have multiple variables or class parameters beneath each other, do we align them, how do we align them, and what about more complex type definitions?

> […]

> Should we break up complex type definitions:
>
> class test (
> String $param1,
> String $param2,
> Integer $param3,
> Variant[String, Integer] $param4 = 80,
> Struct[{
> a => Enum[hi, there, everyone]
> b => Optional[Variant[
> Enum[yo, lo],
> Integer[2]]]
> }] $param5 = { a => 'hi', },
> ) {}
>

+1 for this example.
(I would prefer less whitespaces on the Optional part of the Struct.)

Do we have other examples available which would argue against a style like this one?

> I like this last one best. It limits the length of the line and by splitting up the type definition according to the type we're defining (a hash) it becomes fairly easy for a human to parse. But then, should the Variant after the Optional be on a new line already or only the arguments to Variant since that one can take multiples (like in the way you'd break up an array over multiple lines) etc. etc. etc. I'm still not entirely happy about all the white spacing between the type and the actual variable name but I do like the columnar view it creates.
>
> Eventually we'll be able to create/alias our own types which should limit the amount of crazy before a variable or parameter definition but until then, what do we do? And once we have the ability to create/alias our own types, how do we style those?
>
> We don't have to agree on a "it must be done exactly this anal way" but a loose consensus about what it could look like would be useful.

ACK.

[Henrik Lindberg]

On 2014-11-12 24:33, Martin Alfke wrote:
> Hi Daniele,
>
> many thanks for bringing up the Type style question.
>
> On 10 Dec 2014, at 14:23, Daniele Sluijters <daniele....@gmail.com> wrote:
>
>> With the future parser we can now add type annotations to a whole bunch of things. Usually it's pretty easy, just chuck the type in front of the variable and you're done. But what if you have multiple variables or class parameters beneath each other, do we align them, how do we align them, and what about more complex type definitions?
>> […]
>> Should we break up complex type definitions:
>>
>> class test (
>> String $param1,
>> String $param2,
>> Integer $param3,
>> Variant[String, Integer] $param4 = 80,
>> Struct[{
>> a => Enum[hi, there, everyone]
>> b => Optional[Variant[
>> Enum[yo, lo],
>> Integer[2]]]
>> }] $param5 = { a => 'hi', },
>> ) {}
>>
> +1 for this example.
> (I would prefer less whitespaces on the Optional part of the Struct.)
>
> Do we have other examples available which would argue against a style like this one?

I the geppetto code formatter "column alignment" is done based on a
cluster size. That way, outliers do not cause excessive amounts of
whitespace, and if there are clusters of outliers these in turn form
groups with equal tabulation.
Suggest breaking and indenting inside types unless the entire type fits
within the cluster space.

(I have not tried the type formatting in Geppetto so not sure which
rules Thomas implemented there).

Tip: Optional[Variant[T]] is the same as Variant[Undef, T] (although it
saves you only 3 chars, it may be slightly easier to read as it
reduces the [] nesting level by one).

- henrik

>
>> I like this last one best. It limits the length of the line and by splitting up the type definition according to the type we're defining (a hash) it becomes fairly easy for a human to parse. But then, should the Variant after the Optional be on a new line already or only the arguments to Variant since that one can take multiples (like in the way you'd break up an array over multiple lines) etc. etc. etc. I'm still not entirely happy about all the white spacing between the type and the actual variable name but I do like the columnar view it creates.
>>
>> Eventually we'll be able to create/alias our own types which should limit the amount of crazy before a variable or parameter definition but until then, what do we do? And once we have the ability to create/alias our own types, how do we style those?
>>
>> We don't have to agree on a "it must be done exactly this anal way" but a loose consensus about what it could look like would be useful.
> ACK.
>

--

Visit my Blog "Puppet on the Edge"
http://puppet-on-the-edge.blogspot.se/