Message: previous - next
Month: January 2015

Re: [trinity-devel] Codebase formatting discussion

From: Michele Calgaro <michele.calgaro@...>
Date: Fri, 02 Jan 2015 12:35:54 +0900
Hash: SHA512

>>> Only just for show I attach a style that I used in my projects.
>>> As you can see, I'm used to small indentation => code did not run to the right side so quickly. I do not have
>>> infinitely wide screen :)

I usually use spaces instead of tabs when coding on my own.
Anyhow using hard tabs is a good solution for shared code: each developer can set the tab width to its own liking and
he can be sure the indentation is maintained. For example I use tab width = 2, so the code does not get to the RHS so
quickly. Only disadvantage of using hard tabs instead of spaces is that when opening the file in a text editor that
does not support variable width tabs, the tab is usually 8 spaces and the code goes to the right very quickly.

>>> Unusually looking definition of function parameters is based from the days when it was not used automatic
>>> generation of documentation => description of the parameters was not in a separate documenting comment, but
>>> the definition is self-commenting. Simple symbols used in comments <=> mark parameters simultaneously input and
>>> output, <= mark output parameters and => mark input parameters. At the same time, I have kept the habit of the
>>> parameters order: at first 'i/o' parameters, then 'o' parameters and the last 'i' parameters.
>>> One thing that might be useful for our common rules for TDE is - strictly habit always use braces - even in
>>> cases where the block is a single line.
>>> As I said in the beginning - I attach it only as a demonstration of my habits. I am also flexible and ready to
>>> use the style that we will confirm as default TDE style.
>>> -- Slávek
>> You are correct about always using braces; this I want to see strictly enforced.

I also prefer to always use brackets, even for single line statements. We all agree on this, so good.

>> Unfortunately those detached indented braces make this extremely hard for me to read.  This looks similar to the
>> style used in kwin?
>> In my experience even if the brace is "invisible" after an if the presence of a control statement plus
>> indentation (and combined with the braces always used rule) are more than sufficient as replacement cues.  In
>> effect what I like about placing the brace at the end is that the control statement and brace form a single
>> "statment"; i.e. my eye only has to jump one line to read the next chunk of control flow instead of having to
>> jump two with the second containing a good bit of whitespace.  That same whitespace causes my eye to sometimes
>> miss the initial statement of the next code, forcing a retrack and often pushing something else out of working
>> memory in the process--this is the main reason I tend to mess up the control flow in twin commits and have to go
>> back to fix it.
>> If I were to excercise the power of the BDFL on this project and override the braces to the way I want to see
>> them would this be a major problem?
>> Tim
> Wow, indentation in twin is yet another - I would say, very confusing - because the brackets are at the same level
> of indentation as the block, so is lost completely. Awful.

Funny enough, I also had to code for several years with twin indentation style.
One thing that I can say for sure about styles is that no matter what style you use, if you use it long enough you get
used to it and even what at first might have seem ugly, in the end becomes natural. twin style is a perfect example of
that: at first I really disliked it, but after I got used to it, it was no longer a problem. Not my favorite style though.

> I am aware that the more popular now are brackets at the end of lines. And I, as well as Michele, earlier mentioned
> that we are flexibile and we have no problem adapt to it. In fact, it was enough for the pleasure to me knowing 
> that along with Michele we have the same preference :)

I am flexible, so up to the BDFL's decision.

> But what would prefer a smaller indentation in the switch cases - as featured Michele. Unfortunately I do not know
> whether astyle can be set to such a manner. See attachment.

Yes, I think the indentation for case blocks that I proposed is more logical: the case blocks are indented as a normal
block. Instead the style in GIT adds an extra indentation level, which is somehow counter-intuitive. Just for the sake
of consistent indentation.

>> 3) the developers of the other school can still use their style to
>>> edit code locally before committing using these steps: a) git pull b) c) edit,
>>> compile, test locally until happy d) e) commit
> For this I'll afraid that reformatting sometimes can cause unnecessary changes to the code just because of repeated
> reformatting. This could lead to unnecessarily hard to read commits.

That was only a suggestion. I also thing it is awkward to work like that and just easier to adapt to a new style.
I did some tests and as long as most options are the same in the two styles, it seems to be quite ok.
Also IMO we have to use point d) before any commit to make sure the committed code follows the correct style
(especially when adapting from another style, it is easy to inadvertently introduce some style mistakes).
Alternatively, we can have an automated beautify task running regularly on GIT (for example once a week).

Version: GnuPG v1