[fpc-pascal] FreePascal Coding style

[Vinzent Hoefler]

On Monday 21 January 2008 14:31, Marco van de Voort wrote:
> > On Monday 21 January 2008 13:54, Marco van de Voort wrote:
> > > > |              Push, Pop,
> > > > |              ...);
> > > >
> > > > Now, as you can see, the instructions are laid out tabular (a
> > > > lot of tools [yes, including "elastic tabstops"] I've seen so
> > > > far are unable to handle even that simple case).
> > >
> > > Then you'll add a tool switch to make enums tabbable. That's
> > > actually an easier example than Graeme's original.
> >
> > 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.

> Well, I'd say group of source files yes. And I wouldn't bother with
> it in the first place (which is the point with making it an artform).

Well, it doesn't need an artist, it needs disciplined developers.

> > Also to be checked in into version control in case the source file
> > somehow changes and its formatting configuration needs to be
> > adjusted.
>
> That's the big advantage of doing it automatedly.

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.

> 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. It helps you to keep the general coding 
style by "suggesting" how to layout the code, but it should not force 
you. It should allow you to deviate from the usual rule - if that's 
justified (of course, *this* is a human decision).
Running automated tools over the code destroys the information put in 
there exactly *by* deviating from the rule. If I did that, I did it for 
a reason.

> > I didn't say, it's a requirement. But I don't want a tool to
> > reformat code, which has been explicitely logically ordered for
> > readability, a better overview over the instruction set, and for
> > easier extensionby the coder.
>
> Well, that is the problem indeed. You WANT too much :-)

Oh, common sense is too much already? :D

> 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 it requires 
> human interpretation, it is not simple (and worse, will lead to
> differing opinions in a Team and possible style-wars).

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. If humans come in contact with the code, it should be 
formatted for humans. The computer doesn't care about the number of 
spaces, blank, or comment lines... and it doesn't even care about the 
actual meaning of the code.

> That is btw also the reason why I tend to choose some tool, configure
> it once, and then declare it gold as far as configuring goes.

And my previous paragraph is the reason, why I would never auto-format 
any code. I may use some tool to "preformat" code (code coming from a 
third-party using a totally different coding style or some terrible, 
historically grown, legacy code), but I would never try to destroy the 
original intend of the developer.

> And 
> also discourage purely style guide related commits/thunks. If it
> ain't broke, then don't fix.

If it's not understandable, it's broke.
If it clearly violates an important guide-line of the coding-style, it's 
broke.

Code is not only pure functionality in terms of bits and bytes. It's an 
intend expressed by someone.

> Everybody can check what the tool produces for themselves,
> end-of-discussion. Aspirant sourcecode-artists in my team can pick up
> painting in their own free time.

It doesn't have to do with art. It's fricking documentation.

> > The only problem with those simple rules is that they can bend and
> > there's no tool yet which knows how far it may bend the rule for
> > formatting a certain piece of code... ;)
>
> And worse, no person either, if you have several.

Well, as long as they obey the rules...

> > There's only one: You need to easily understand it when you read
> > it. Even if you read it 10 or 15 years after it has been written.
> > 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?

> > In other words: Sexy code is easier to understand. ;)
>
> If you are attracted to THAT kind of sexy alone. Tastes vary.

I did it on purpose. Usually a discussion gets more attention after sex 
has been thrown into it. ;)


Vinzent.