[fpc-pascal] FreePascal Coding style

[Vinzent Hoefler]

On Monday 21 January 2008 15:59, Marco van de Voort wrote:
> > On Monday 21 January 2008 14:31, Marco van de Voort wrote:
> > > > Oh, come on. What if you encounter an enum that does *not*
> > > > require such "tabbing" inside the same source file.
> > >
> > > Well, "require" or not is relative to begin with.
> >
> > Let me rephrase it: A tool would have destroyed information if it
> > would have reformatted such code. That's simply not tolerable.
>
> Let me rephrase mine too, is it a requirement to have such code meta
> information in your system?

It is a requirement that the code should as self-explainable as 
possible, yes.

> For me it is only a base readability line, but I have no desire what
> so ever to go into detail.

Ok, let me show you a real life example of "deviations from the rule":

1)
|   Ksi := Ksi + self.Weight[Pred (Layer), j, k] *
|                self.Value[Pred (Layer), j];


2)
|   Ksi := Ksi + self.Weight[Pred (Layer), j, k] *
|          self.Value[Pred (Layer), j];


What is more readable? Usually the next line should be aligned, true, 
but with the operator precedence the first variant just makes more 
sense.

> If you find one, please notify me. Somehow developers can only be
> disciplined on schemes they thought up themselves.

No, they're usually disciplined on schemes they found senseful. That's 
different.

> > That's what the guy told us, too. It never worked out. Coders wrote
> > code, checked it into CVS and it came out differently. The didn't
> > even know their own code anymore, just five seconds after they
> > committed it.
>
> Well, I never said I put it in a post commit event.

Well, that's what he tried to do to us. And not even because he was the 
senior software engineer, but because he happened to be the server 
admin.

Of course, the source code quality didn't match up. If you know that 
your code gets destroyed once you commit it, you don't take much care 
to do it right.

> I just do (did is 
> a better word, currently I'm on my own again) it regularly by hand
> with an automated tool.

As I expressed already: I have nothing against tools *checking* given 
guide-lines. But in the end it's the developers responsibility to 
follow those.
So if the developer decides to let the tool reformat his code and 
manually tweak those couple of lines where the tool gets it wrong, it's 
ok.

> The developers are supposed to keep it basically readable, and
> periodically the automated tool over it catches their glitches,

It's not a glitch if code is laid out to be better understandable:

A matrix based filter calculation as written by the developer:

|Summe :=
|      Prev_D^[i - 1] + 2 * Prev_D^[i] +     Prev_D^[i + 1] + 
|  2 * Cent_D^[i - 1] + 4 * Cent_D^[i] + 2 * Cent_D^[i + 1] +
|      Next_D^[i - 1] + 2 * Next_D^[i] +     Next_D^[i + 1];

The same code raped by "ptop" with default config:

|Summe :=
|         Prev_D^[i - 1] + 2 * Prev_D^[i] +     Prev_D^[i + 1] + 
|         2 * Cent_D^[i - 1] + 4 * Cent_D^[i] + 2 * Cent_D^[i + 1] +
|         Next_D^[i - 1] + 2 * Next_D^[i] +     Next_D^[i + 1];

The whole layout is totally lost. Its definitely not readable anymore.

> > > You only do it
> > > periodically (e.g. on a big release), and for the rest you don't
> > > enforce, but just keep it minimally readable by hand.
> >
> > That's what an editor is for.
>
> The editor is primarily to get work done.

Work is done with paper and pencil. :P

> Amelioration is a cost 
> factor, and it should be minimized. Most of the gains are in the
> simplest of things

And as only 10% of a software project involves actually writing code, 
there's not much optimization potential here, anyway.

Being able to read the code is much more important after all.

> Yes. But there are two, maybe three reasons I don't want that, at
> least not in normal business code:

See the example above. It's not about the decision if you should two, 
three, or four spaces or rather use tabs, or if the line length should 
be limited to 72, 80, 127, or even 4095 chars or if you put spaces 
around parentheses or not. Those are details you get accustomed to more 
or less (although it pays to not deviate too much from normal written 
text).

The point is: if I already have trouble reading code, how much trouble 
would I have actually understanding it?

> - People constantly correcting minor glitches in style and committing
> those, poluting the RCS history.

Oh come on. History can be filtered. And I'd rather have a "typo and 
coding-style fixed" commit only, than this typo and code-style fix 
commited *together* with a totally unrelated change.

This does not only pollute the history, it pollutes the diff which is 
much more important.

> - In general, don't spend too much time on style. Better invested on
> actual code quality commenting and readability than in how it is
> formatted.

You would wonder how much quality *can* be in formatting.

> > > Per enum decision to tabbed or not is not simple.
> >
> > Yes, it is: If it's done that way, it's probably meant to be that
> > way, so don't touch it. The tool may check if the colums are
> > correctly aligned then, though. ;)
> >
> > But in no case it should reformat it.
>
> _If_ I really encountered such a remote case, I'd extract it to an
> .inc (something so perfect warrants an own file), and exclude it from
> the automatic run, and assign its maintenance to one single person.

You're kidding. Such cases aren't even remote.

> > As I said, code is for humans. If it doesn't require human
> > interpretation it's probably auto-generated and then I don't care
> > about the formatting.
>
> Yes. But you seems to assume that the amount of time invested in
> making it readable is linear with the benefit you get from it. It
> isn't.

And you seem to assume that the time I am spending on formatting code 
actually matters. Even if it's 10% of the time I am spending on writing 
code, it's only 1% of my total development effort. But it may benefit 
10 or 20 developers reading the code, which may save them a lot more 
than the time I spend making the code.

Most people seem to forget that software development is about yourself 
writing the code. That's wrong. It's about the psychopath hired after 
you, who inherited your code and knows where you life. If you write 
your code with that in mind, it'll be good. ;)

> > If humans come in contact with the code, it should be formatted for
> > humans
>
> So? Why can't machine generated output not be human readable?

Call it experience. Usually it isn't:

|   String value[] = null;
|   int _len0 = istream.read_long ();
|   value = new String[_len0];
|   for (int _o1 = 0;_o1 < value.length; ++_o1)
|      value[_o1] = istream.read_string ();
|   return value;

Not even if it would have been properly formatted. So why bother?

> I 
> assume you have read text where the wordwrapping, hyphenation and
> linebreaking is done by a machine instead of a human? Why? Because a
> machine does a way more consistent job.

Oh really? And that's why it took D.E.Knuth took 20 years to develop 
TeX? Because it's all so fricking "easy"?

> > > > And contrary to popular beliefs, there's a substantial amount
> > > > of visual appearance involved.
> > >
> > > Yes. But I go for the 80%, not the 100% in this case.
> >
> > So why need the tool? If you can't trust the developers to maintain
> > a certain style, how trustworthy is their code?
>
> To have a clear baseline, and to not get caught up in continuous
> style fixes. The automated tool will get it at the end of the period
> anyway.

And it will occasionally destroy beautiful, perfect code on its course.


Vinzent.