Nick Hodges

Delphi Development Pretty Good Practices #3 – File Setup

28 Apr

Okay, hopefully by now you’ve read the introduction of this series, and you’ve downloaded (or better yet, pulled from source control) the latest version of TextScrubber and given it a once over.  In this installment, I’m going to discuss the file structure of the project and why I did things the way I did.

First, an admin note:  I’ve made some small changes to the code for TextScrubber.  You can get these by going to the main directory for your code and typing svn up.  They aren’t any big deal – comments, some cleanup and organization, but it sure is easy to get the latest changes, isn’t it.

Taking a look at the file set that makes up the TextScrubber project, you see a number of different files, each with a particular purpose. I’ll describe each file in turn, telling what its purpose is and why it exists.  Future installements will go in depth a bit more.

TextScrubberProjectManager

FileName

Discussion

frmAboutBox.pas Every Application should have an About Box.  The About Box should display the Application Icon, give Version information, copyright notices, and contain a short description of what the application is or does. 
frmStraightText.pas This is the “main form” for the application, but since TextScrubber doesn’t have a main for, but it simply a container for some non-visual controls.
frmTextScrubberOptions.pas Every application should have a single dialog that allows the user to set all the configurable options and preferences for the application.
NixUtils.pas NixUtils.pas is a general purpose file of handy utilities and routines that I’ve built up over the years.  I use it in TextScrubber, so I’ve included it in the project.  Normally, I keep this file in a separate directory.
uTextScrubber.pas This is the “workhorse” unit that contains the class that does all the work of the application.
uTextScrubberConsts.pas This file has one and only one purpose:  To hold all the constants for the project. It will include all constant declarations, as well as the strings declared with resourcestring.
uTextScrubberTypes.pas This file contains all the types declarations for the project, including classes, enumerations, records, etc.
uTextScrubberUtils.pas This file contains those little, standalone, “helper” routines that you use to build the product.  Routings that go into this unit are often considered as candidates to end up in NixUtils.pas, but most often, they are very specific to a purpose of the project.

A Note About Naming Conventions

For this project, I’ve used a pretty simple naming convention. For filenames, I put ‘frm’ at the front of forms, ‘u’ at the beginning of standalone units. DataModules would get ‘dm’. Constants start with ‘c’, and resourcestrings start with ‘str’.  Parameters are prefixed with ‘a’, and all local variables (well, almost all) are prefaced with ‘Temp’.  Those latter two help keep things straight inside class methods.  I try to make my identifiers descriptive, and I never worry about their length.  A well named identifier makes code clearer, and Code Completion can do all the work if you are worried about typing.  (But in my view, you should never worry about typing if typing less means writing unclear code…..)

I use those as a general set of rules, but I’m not dogmatic about it.  I try to be consistent for my and your benefit.  The exact rules of naming aren’t nearly as important as having a naming convention.  My recommendation is to find a system that you like and stick with it.  Naming conventions are a great source of religious debates. I generally leave that to others, and simply recommend that you find something that works for you and stick with it. 

More Detail to Come

I’ll be talking a bit more specifically about each of the files in future installments.  This entry should just give you a brief rundown on the basics.

13 Responses to “Delphi Development Pretty Good Practices #3 – File Setup”

  1. 1
    Ken Knopfli Says:

    Good stuff. Prefixing file names, not just code, is a good idea.

    "The About Box should … contain a short description of what the application is or does."

    How I wish this were more widespread - esp. in shareware!

  2. 2
    Dimonka Says:

    I use the similar notation, but there are some other type of Delphi element, that should be differentiated by name, like Data Modules or Frames.

    Thus I use prefixes:

    dm - for a Data Module
    fm - for a Form
    frm - for a Frame
    u - for other units

    There is another good practice - create a folder for a particular group of units, forms and frames. That makes project even more structured.

  3. 3
    Stamp Says:

    Another awesome post! I have a question though: When dealing with forms, what do you name the form? Do you also name it frmAbout?

    I ask this because Delphi doesn’t allow the same filename as the unit (multiple resources). As a workaround, I name my forms formAbout.pas, and the name of the form frmAbout. I use Delphi 7 btw.

  4. 4
    Wouter Says:

    If the syntax highlighter would be a bit more intelligent, we wouldn’t need most of these naming conventions.

    A little icon or a different style would be more useful, and at least it would be consistent, even when you’re editing code from people who don’t use the same convention.

    uOooo for units
    cOooo for constants
    AOooo for arguments
    FOooo for private members
    TOooo for types
    IOooo for interfaces
    TOoooRec for records
    POooo for pointers
    HOooo for handles
    LOooo for local variables
    GOooo for global variables
    EOooo for exceptions
    Oooo for properties

  5. 5
    Dimonka Says:

    Stamp,
    I use the following names:
    FormXXX - for forms
    FrameXXX - for frames
    DataModuleXXX - for data module

    Then in the list of forms you can immediately recognize what is what.

  6. 6
    Steven Says:

    I used to use those same naming conventions, but on some projects I’ve used something a little different.

    Inside my source folder, I have two sub-folders, gui and units. I don’t prefix the form units names with "frm" but put all forms inside the gui folder. Why? On projects with a lot of forms, I find it easier to find a particular form on Project Manager by typing the first letter of the form, say D for Dimmer. If I had prefixed the frm before (frmDimmer), it would be harder to locate it on the list by typing the first letter.

    For those who prefix the forms units with frm, how do you locate a specific form on the Project Manager? Is it manually by browsing the list or am I missing any Delphi IDE functionality for this?

  7. 7
    P Says:

    People here use the extended "View unit" dialogue (which is part of DDevExtentions, I think). The default key combo is Ctrl + F12 and it pops up the dialogue. You can start typing the unit name and it’ll show matching units. So if you have FrmDimmer and you type "Dim" and hit enter, you’ll find yourself in FrmDimmer.

    I’ve used the same system Stamp mentioned, i.e. FormFoo for the pas and FrmFoo for the form.

  8. 8
    Markus Says:

    @Nick,

    just for consistency: Shouldn’t your NixUtils.pas not be named uNixUtils.pas ? (Well, in that case this gives your Utils unit an interesting connotation).

  9. 9
    fabio vitale Says:

    Delphi Standards: Naming component instances:

    http://www.delphi1.com/Articles/Abbreviations.htm

    Delphi Standards: The Case for Suffixes:

    http://www.delphi1.com/Articles/TheCaseForSuffixes.htm

  10. 10
    R2C2 Says:

    I’m a bit late in commenting this, I know. But perhaps you’ll read it anyway.

    Concerning the choice of the files you wanna use: Do you think that’s a good idea? Types.pas, Consts.pas, Utils.pas, …

    Such units are state-of-the-practice but are they really "pretty good" meaning state-of-the-art? I feel they lead to grouping code by syntax (putting constants in Consts.pas and types in Types.pas, etc.). But OOP says: group by semantics, not by syntax.

    Sometimes there might not be a good place for some commonly used constants or types but IMHO in most cases there is.

    For example you use strVersion just in frmAboutBox.pas. This ties your AboutBox to the constants unit. When you wanna reuse the AboutBox in another program, you have to either drag along constants you don’t need or you have to manually select the needed constants and add them to the project specific Consts.pas. You could reduce coupling by putting the constant in uAboutBox.pas.

    On the other hand in the Types.pas you have types considered with the clip board others managing version information, etc. You could increase cohesion by separating different concerns in different units which also makes reuse easier.

    What do you think? Old habit, a trade-off game, or some real advantage?

    Christian

  11. 11
    Nick Hodges Says:

    Christian –

    I think you are right. One of the articles I have planned is to refactor the About Box for that very purpose. I agree that my approach isn’t the best for the situation that you describe.

    Nick

  12. 12
    Unexpected Text Message Blows Up Suicide Bomber In Safe House | TextingNews.info Says:

    [...] Nick Hodges » Blog Archive » Delphi Development Pretty Good … [...]

© 2014 Nick Hodges | Entries (RSS) and Comments (RSS)

Your Index Web Directorywordpress logo
Close