[fpc-pascal] FreePascal Coding style

[Marco van de Voort]

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

For me it is only a base readability line, but I have no desire what so
ever to go into detail.
 
> > 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.

If you find one, please notify me. Somehow developers can only be
disciplined on schemes they thought up themselves.
 
> > > 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.

Well, I never said I put it in a post commit event. I just do (did is a
better word, currently I'm on my own again) it regularly by hand with an
automated tool. Usually on what a human judges is a junction in the
development ( a major release, addition of a major subsystem etc). Some
files might be excepted from the process etc. 

The developers are supposed to keep it basically readable, and periodically
the automated tool over it catches their glitches, and erases artwork and
other mistakes. This also means that a new developer can start without too
much instruction (put begin and end always on a new line, indent two spaces,
camel case identifiers but don't over do it, and don't do hungarian
notation except for form components and exceptions. Ok, you can start now.
If they have Delphi experience, it usually doesn't even generate questions)

> > 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. Amelioration is a cost factor, and
it should be minimized. Most of the gains are in the simplest of things

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

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

- the endless feuding over what constitutes the proper style (including
  writing complete books over coding style that nobody ever reads, except
  the person that wrote it in the first place)
- People constantly correcting minor glitches in style and committing those,
  poluting the RCS history.
- 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.

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

Yes. Common sense is to variant amongst people. It is usually just a way to
make "I'm right" sound like "we all agree on this"
 
> > 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.
 
> > 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.

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.

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

[snip]

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

Well, they will. The first two days.....

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