[fpc-pascal] FreePascal Coding style

[Marco van de Voort]

> 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.
 
> Of course you can do it all configurable until the tool formats as you 
> would like it to format, but in the end this leads to one tool 
> configuration per source file.

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).

The only exception that I make is if the source is your actualy product (if
you sell components with source, or publish FPC RTL). 

And e.g. FPC already has a metafile per sourcefile in the documentation, so
having some formatting options there is not _THAT_ strange. Verbatim (don't
touch) is then also an option.

(not that I plan to add this anytime soon)

> 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. 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. 

> > Note that this is the first time that I actually saw this enum
> > formatting as an requirement. Do you have a criterium for this?
> 
> 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 :-)

> > > And even if the tool is a bit more intelligent and detects the
> > > tabular design, how is it supposed to know which instructions are
> > > more similar to the other and should appear in a row and which ones
> > > not?
> >
> > If you make coding standards an artform, you'll need an artist.
> 
> No. A simple set of rules is sufficient.

Per enum decision to tabbed or not is not simple. If it requires human
interpretation, it is not simple (and worse, will lead to differing opinions
in a Team and possible style-wars). 

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 also
discourage purely style guide related commits/thunks. If it ain't broke,
then don't fix.

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.

> 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.

> > The only exception I can see is documentation, but then you'll need
> > meta info to the formatter. Either in source, or out source
> > (unitname.enumx.style:=tabular or something in some metafile)
> 
> Yeah, great. Just like /*INDENT-OFF*/ in each and every C-source file 
> I've ever checked into the company's CVS before we threw out the whole 
> auto-formatting on check-in.

See above. I despise in-source metadata, which is why I like fpdoc so much.

> > > Code is primarily written for humans. Otherwise we wouldn't care
> > > about the formatting. Interestingly, to format code properly you'd
> > > need to understand it. And that's something that currently only a
> > > human can do.
> >
> > Depends on your definition of "properly".
> 
> 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. And safe 50% in
discussion in the process.
 
> In other words: Sexy code is easier to understand. ;)

If you are attracted to THAT kind of sexy alone. Tastes vary.