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
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
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
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
Hier ist auch eine Liste mit Präfixen enthalten- Delphi Identifier Naming Conventions
von Zarko Gajic
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.
- [Archive] Uwe Raabe on Twitter: “New article …”
- [Wayback/Archive] Async Tasks in VCL Projects – The Art of Delphi Programming <——— this is where the code example comes from
- [Archive] Jeroen Wiert Pluimers on Twitter: “So you put the files in a digital signal processor? (which is the reason I recommend against using abbreviations when naming things in software as abbreviations are very context sensitive)… “
- [Archive] Uwe Raabe on Twitter: “Another one is
selfor Select used radiogroups or comboboxes. I prefer to prefix the usage and not the control type.… “ - [Archive] Jeroen Wiert Pluimers on Twitter: “I first saw the
TSearchFormname, and thought “Yay, finally someone else getting the very useful naming convention which puts technology at the end and goes without abbreviations”. Then camedspand other shortcuts in the mix. Bummer (;… “ - [Archive] Uwe Raabe on Twitter: “Sorry to have disappointed you.… “
- [Archive] Jeroen Wiert Pluimers on Twitter: “To problem, was just trying to figure out the why.… “
- [Archive] Uwe Raabe on Twitter: “Style Guide – never perfect, but always better than none… “
- [Archive] Jeroen Wiert Pluimers on Twitter: “Which of the style guides do you use? I know there are a few; I thought I had posted a blog articles about them, but didn’t, so need to find where I used to name them in training/session materials and try to get one up at a later stage.… “
- [Archive] Uwe Raabe on Twitter: “I try to follow the Delphi Style Guide as described in the docwiki: … I admit that there are some old habits that don’t match it exactly. Trying to get better.… “
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
- [Wayback/Archive] Introduction – RAD Studio
- [Wayback/Archive] General Rules: Identifiers, Keywords, Indentation – RAD Studio
- [Wayback/Archive] Source Code Files, Units and Their Structure – RAD Studio
- [Wayback/Archive] White Space Usage – RAD Studio
- [Wayback/Archive] Comments – RAD Studio
- [Wayback/Archive] Statements – RAD Studio
- [Wayback/Archive] Type Declarations – 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
The Wiert Corner - irregular stream of stuff 