Reminder to self: write a more extensive blog post on Delphi style guides and code style in general

jpluimers

Nov 30

A while ago, Uwe Raabe reminded me about the Delphi Style Guide which is on-line at the Embarcadero document wiki:

He reminded me to write a bit more about Delphi Style Guides, as there are a few and I used them on past conference sessions.

I thought either the blog post or the conference sessions were already online.

Nope, no 2010 conference sessions at [Wayback/Archive] jpluimers/Conferences: Materials for the conferences that Jeroen Wiert Pluimers spoke on., and no blog post yet.

Hopefully over time I will update that repository, but for now: here is a summary of Delphi Style Guides and a short hint on why to get naming conventions right.

I might extend both in a later blog post, health and time permitting.

Delphi Style Guides

Style guides I found in the past as files named in those session materials:

Delphi Identifier Naming Conventions.pdf

This is the "Delphi Identifier Naming Conventions" blog post on About.com by [Wayback/Archive] Žarko Gajić.

I originally saved it from delphi.about.com/od/standards/l/bldnc.htm, and luckily it made it into the WayBack machine.
Econos - Coding Standard Document.pdf

This was the style guide at by [Wayback/Archive] Stefan Hoffmeister and too archived into the Wayback machine
JCL Delphi Language Style Guide.pdf

This is now online as part of the JCL Wiki at [Wayback/Archive] Project JEDI Delphi Language Style Guide - Project JEDI Wiki.
Object Pascal Style Guide.pdf

This one is by [Wayback/Archive] Charlie (Charles) Calvert and still online at [Wayback/Archive] Object Pascal Style Guide.

Charlie has [Wayback/Archive] his own YouTube channel as well.

The above also made me find this interesting post: [Wayback/Archive] Delphi-PRAXiS - Einzelnen Beitrag anzeigen - Delphi Einrücken ::: ::: Wie rückt ihr ein? which mentions these style guides (I modified all links to point to the most recent WayBack machine version that is complete)):

Borland empfiehlt folgende Formatierungsregeln:
http://community.borland.com/article/0,1410,10280,00.html
Der Punkt 3 "naming conventions" schweigt sich aber über Deine Frage aus

Deutsche Übersetzung der Borland Style Guides
http://www.dsdt.info/grundlagen/styleguide/
Unsere Freunde von dsdt.info haben sich die Mühe gemacht und dem Text ins deutsche Übersetzt.
Damit gibt es nun keine Ausreden mehr sich nicht an die Richtlinien zu halten

Delphi 4 Developer's Guide Coding Standards Document
von Econos - Stefan Hoffmeister (1998)
basiert auf dem Coding standard von Xavier Pacheco and Steve Teixeira
http://www.econos.de/delphi/cs.html
Hier gibt es auch eine Liste mit Präfixen zu den einzelnen Komponenten

Delphi Object Pascal Coding and Project Organization Standard
von Michael P. Hollis and Mark S. Lauter
http://onelauter.com/codestandards/
Hier wird zwar auch nicht auf die Präfixe eingegangen, aber es wird unter anderem auch eine Verzeichnisstruktur vorgeschlagen.
Solch ein Dokument mit den einzuhaltenden Regeln sollte in jedem Projekt / Team existieren.

Delphi coding Standards
Maintained by Mustafa GÖKMEN
http://gokmen.selcuk.edu.tr/document.../delphi/cs.php
Hier ist auch eine Liste mit Präfixen enthalten

Delphi Identifier Naming Conventions
von Zarko Gajic
it made it into the WayBack machine
Dieser Artikel befasst sich nur mit der Benamung von Variablen

The dstgroup version is based on WayBack: onelauter.com/codestandards/CodeStandards.doc.

Mixed emotions conventions

Anyway, this is the piece of code by Uwe Raabe that made me frown as it mixes two Delphi styles at once and uses improper meanings in names:

procedure TSearchForm.StartSearch; begin   StatusBar.SimpleText := '';   dspFiles.Clear;   Files.Clear;   BeginSearch;   SearchFolder(edtRootFolder.Text, edtSearchPattern.Text);   EndSearch; end;   procedure TSearchForm.SearchFolder(const APath, ASearchPattern: string); var   arr: TArray;   dir: string; begin   arr := TDirectory.GetFiles(APath, ASearchPattern);   AddFiles(arr);   { release memory as early as possible }   arr := nil;   for dir in TDirectory.GetDirectories(APath) do begin     if not TDirectory.Exists(dir) then Continue;     SearchFolder(dir, ASearchPattern);   end; end;   procedure TSearchForm.AddFiles(const AFiles: TArray); begin   Files.AddStrings(AFiles);   dspFiles.Items.Count := Files.Count;   StatusBar.SimpleText := Format('%d files found', [Files.Count]); end;

This is the start of technical debt, and resulted in the below cool Twitter thread.

Note that I intentionally used "Digital Signal Processor" as dsp abbreviations are very context sensitive, causing truckloads of problems especially when switching between functionality at front and technical stuff at front in naming conventions.

Functionally, it could have made very much sense to add files into a list to be passed onto a Digital Signal Processor for pre- or post-processing of signals.

Uwe uses this Style Guide (which regrettably does not pay tribute to the original author):

[Wayback/Archive] Delphi's Object Pascal Style Guide - RAD Studio

So yes, Uwe posted a cool example on how to apply technology properly, and I retweeted it as this: [Archive] Jeroen Wiert Pluimers on Twitter: "Async Tasks in VCL Projects. Cool example on how to properly to Async in VCL. Important thought: please do not mix naming conventions like Uwe does, as it is substantially adds to your technical debt.… "

It is also a reminder for me to phrase this into the positive form: stick to one naming convention as it makes less technical debt creep in. Like Uwe, I learn new things every day and be reminded it is hart to not follow old habbits.

--jeroen

Comment