Guidelines for Writing Delphi Programs

Over the years, I have used components written by several companies. There are a number of problems that seem to be repeated - this lists a few the are easy to avoid.

Existing Style Guides

There are several design guidelines available online - such as

Object Pascal Style Guide (by Charlie Calvert) is pretty interesting ... even if you do not follow it - In fact, I disagree with a lot of it (alternate link)
Delphi 4 Developer's Guide Coding Standards Document is also pretty good ... though I disagree in a few places

Though both of these are pretty good (and well worth reading), I suggest the following modifications.

Use columns

The Borland guidelines suggest using only a single space on each side of an assignment statement and do not allow any spaces on either side of a period that is used to separate properties and methods from the object identifier.

I disagree - spaces can be used to improve readability. Consider these

Borland's Suggestion
Port := IBQuery_Basic.FieldByName('Port').AsString ; Sort_Order := IBQuery_Basic.FieldByName('Sort_Order').AsString ; Comment := IBQuery_Basic.FieldByName('Comment').AsString ; Active := 'Y';
With Spaces
Port := IBQuery_Basic.FieldByName('Port') .AsString ; Sort_Order := IBQuery_Basic.FieldByName('Sort_Order').AsString ; Comment := IBQuery_Basic.FieldByName('Comment') .AsString ; Active := 'Y';

Borland's Suggestion

Port := IBQuery_Basic.FieldByName('Port').AsString ;
Sort_Order := IBQuery_Basic.FieldByName('Sort_Order').AsString ;
Comment := IBQuery_Basic.FieldByName('Comment').AsString ;
Active := 'Y';

With Spaces

Port       := IBQuery_Basic.FieldByName('Port')      .AsString ;
Sort_Order := IBQuery_Basic.FieldByName('Sort_Order').AsString ;
Comment    := IBQuery_Basic.FieldByName('Comment')   .AsString ;
Active     := 'Y';

In general, Borland follows their guidelines, but occasionally, even they line up assignment statements.

I suggest that any time spaces can be added to make code easier to read ... do it.

On the other hand, when only a single space is used before the colon, then searching for an assignment statement becomes much easier - it is nearly impossible with a variable number of spaces.

if..then..else

The Borland guidelines suggest using separate lines for begin and end - I think that this is a waste of space.

Borland's Suggestion	Fewer lines
if a = b then begin ... end else begin ... end;	if a = b then begin ... end else begin ... end;

Long Strings

The Borland guidelines specifically state not to start a line with an operator. I disagree - I frequently find it easier to read code that starts with operators.

Borland's Suggestion
s := 'select "Experiment_Master_tbl"."Name" ' + ' FROM "Experiment_Master_tbl" INNER JOIN "Project_Master_tbl" ' + ' ON "Project_Master_tbl"."Project_ID" = "Experiment_Master_tbl"."Project_ID" ' + ' where "Project_Master_tbl"."Name" = ''' + Project + '''' + ' ORDER BY "Experiment_Master_tbl"."Name"' ;
Starting with Operators
s := 'select "Experiment_Master_tbl"."Name" ' + ' FROM "Experiment_Master_tbl" INNER JOIN "Project_Master_tbl" ' + ' ON "Project_Master_tbl"."Project_ID" = "Experiment_Master_tbl"."Project_ID" ' + ' where "Project_Master_tbl"."Name" = ''' + Project + '''' + ' ORDER BY "Experiment_Master_tbl"."Name"' ;

Borland's Suggestion

  s :=
       'select "Experiment_Master_tbl"."Name" ' +
       '  FROM "Experiment_Master_tbl" INNER JOIN "Project_Master_tbl" ' +
       '    ON "Project_Master_tbl"."Project_ID" = "Experiment_Master_tbl"."Project_ID" ' +
       ' where "Project_Master_tbl"."Name" = ''' + Project + '''' +
       ' ORDER BY "Experiment_Master_tbl"."Name"'
    ;

Starting with Operators

  s :=
       'select "Experiment_Master_tbl"."Name" '
     + '  FROM "Experiment_Master_tbl" INNER JOIN "Project_Master_tbl" '
     + '    ON "Project_Master_tbl"."Project_ID" = "Experiment_Master_tbl"."Project_ID" '
     + ' where "Project_Master_tbl"."Name" = ''' + Project + ''''
     + ' ORDER BY "Experiment_Master_tbl"."Name"'
    ;

In long string concatenations like these, I frequently debug by commenting out one of the strings. In the first case, if the ORDER BY string is removed, I have to remember to also remove the plus sign from the previous string ... and to replace it when the string is reactivated. Another nice touch is placing the semicolon on a separate line ... for much the same reason.

I also do this with long if statements that require multiple lines - except in this case I start the lines with and or or and line up the parameters.

Underscores

I don't know why the guidelines continuously remind the developer NOT to use underscores in variable names. Specifically, I find that their use makes for much more readable code.

Borland's Suggestion
ThisIsAComponent.Parameter
With Underscores
This_is_a_Component.Parameter

with Statement

The with statement can be used to implicitly associate properties and methods with an object. The Delphi help indicates that this construct will also make the program run faster.

However, the with statement makes development and debug much more difficult.

For instance, in debug when you place the mouse cursor over a variable, the IDE shows the current value of the variable. When with is used, this capability is lost.
When reading source, ObjectName.Parameter is pretty obvious. But when with ObjectName is used, all you see is Parameter. If the programmer is not completely familiar with all the object's possible parameters, this can be fairly unreadable. This can be made much worse by including several objects in the with clause ... which is suggest in the help files.

Naming Conventions

Generally, I don't believe in strong naming conventions, but I do believe in readable code.

General Naming Conventions

Delphi is not case-sensitive.

The following definitions are followed but not enforced

TName	All type definitions begin with T
FProperty	The private class variable used to store a property's value starts with F (field)
OnMouseClick	Most event names begin with On
LVarName	Local variables, not usually used for single letter variable names - i, j, k, x, y, z
PVarName	A variable passed as a parameter. The Delphi VCL uses A instead of P. The common parameters Value and Message are used without a prefix.
PTName	Pointer to an object of type TName.

"A good guideline is that method names have verbs in them. If you find that you create a lot of methods that do not have verbs in their names, consider whether those methods ought to be properties." from the Delphi Help

Most property methods start with either Set or Get; events start with On.

User Interface Components

SaveData_UIButton

Menus

_UIMenu

Menu_File_Open
Menu_File_Save
Menu_File_SaveAs
Menu_File_Exit

Menu_Edit_Copy
Menu_Edit_Paste
  ...

Other form components that are part of a larger group should follow a similar format, including

Items on a tool bar - the names should start with the name of the toolbar (assuming that they are statically assigned)

Custom DialogBoxes and Sub-Forms

Form_Grp1_Action1
Form_Grp1_Action2
Form_Grp1_Action3

Form_Grp2_Action1
Form_Grp2_Action2

Form_Grp3_Action1
  ...

Forms are actually a bit more complicated - they have both a form name and a unit name (which is also used to name the *.dfm & *.pas files) ... and these two names must be different. In most cases, this is no big deal since an application has only one form

Form name   xyz_Form
Unit name   xyz_frm
File names  xyz_frm.dfm, xyz_frm.pas, xyz_frm.dcu ...

However, when an application contains lots of forms, .... (I am still working on this - 08-30-06)

Other References

Also see my NamingConventions page.

Author: Robert Clemenzi - clemenzi@cpcug.org