Directives

[Previous] [Next]

2.1 Never hard-code application-specific or component-specific values in object templates.

Object templates should be made as generic as possible. Since you can rarely know in advance the project in which the objects might end up, you have to design your objects accordingly . There are essentially three mechanisms you can use to ensure that the data used and displayed by a template object is the proper data for the project in which the object resides. You can

• Reference the App object properties whenever possible.
• Provide functions and properties that the host project can call to set values within the object.
• Use a common set of global constants (and variables , if absolutely necessary).

Using parameters of public procedures is probably the best way to share data from a project with a template object. This mechanism allows you to create template objects as independent units. A developer only has to call the procedures in the object, passing the appropriate arguments, for the object to be integrated. This creates very modular and "black box"-like objects. You can design objects that rely on global variables or constants from the project to which they are added, but this reduces the modularity of the objects and generally means more work must be performed during the integration of the object.

NOTE

---

It's important to use constants in place of hard-coded "magic" numbers within an object template so that developers can easily understand and replace the values.

Practical Applications

If any values within an object will be dependent on the project to which the object is added, do not hard-code those values. Make your object templates as "ready-to-go" as possible by minimizing the amount of code that needs to be added or modified within the object when the object is added to a project.

2.1.1 Never hard-code paths in an object template. Paths change from application to application and from installation to installation. Just as you should never hard-code a path in any object whatsoever, you should also never hard-code a path in an object template. The developer using the template might not realize that the hard-coded path exists, and this could cause the project to fail, crash, or, worse yet, modify inappropriate files.

Incorrect:

 Me.Picture=LoadPicture("C:\ProgramFiles\MyApp\Splash.bmp") 

Correct:

 Me.Picture=LoadPicture(App.Path&"\Splash.bmp") 

Also correct (but using a global variable is not preferred):

 Me.Picture=LoadPicture(g_strPath&"\Splash.bmp") 

2.1.2 Never hard-code the application name in an object template. Because each application has its own name, never hard-code an application name in an object template.

Incorrect:

 '*NOTE:Needtochangeapplicationtitlewhen '*addedtoaproject. 

 Me.Caption="AboutApplication" 

Correct:

 Me.Caption="About"&App.Title 

2.1.3 Never hard-code a version number in an object template. A common form template is the About box, which often shows version information. If a template object displays data that can be retrieved from the App object, always pull that information from the App object.

Incorrect:

 '*NOTE:YoumustreplaceX.X.Xwiththecurrentversionofthe '*applicationwhenthisobjectisaddedtoaproject. 

 lblVersion.Caption="VersionX.X.X" 

Correct:

 lblVersion.Caption="Version"&App.Major&"."&_ App.Minor&"."&App.Revision 

2.1.4 Expose properties for template objects to accept data from the host applications. Rather than expose public variables or use global variables, use Property procedures. Property procedures allow you to perform data validation and execute code when the values change.

Incorrect:

  Public  m_strUserName  AsString  

Correct:

  Private  m_strUserName  AsString PublicPropertyGet  UserName()  AsString  UserName=m_strUserName  EndProperty PublicPropertyLet  UserName(strNewUserName  AsString  ) m_strUserName=strNewUserName  EndProperty  

2.2 Provide extensive comments in object templates, particularly where modifications are required.

It's rare that you'll be able to add a template object to a project and not have to make some changes to it. You need to make it is as easy as possible for a developer (including you) who adds the template object to a project to know where and what changes are necessary to integrate the object with the project. One way to do this is to use a consistent mechanism for denoting comments that explain required changes and to document this notation in the Declarations section of the module. A developer can then easily search for the comments and make the changes as necessary.

For instance, you could denote comments that show where changes are necessary like this:

  If  txtPassword="password"  Then   '*NOTE:Placecodeheretopassthe '*successtothecallingprocedure.  LoginSucceeded=  True  Me.Hide  Else  MsgBox"InvalidPassword,tryagain!",,"Login" txtPassword.SetFocus SendKeys"{Home}+{End}"  EndIf  

You could then document this in the Declarations section of the module as follows :

 '*Allareasofcodewheremodificationsarenecessary '*tointegratethisobjectwithaprojectaredocumented '*withcommentsdenotedbyNote:. '*Tolocatethesecomments,searchfor'*NOTE:. 

Do this consistently in all your object templates, and you'll reduce the time and effort necessary for objects based on your templates to be integrated into projects. The more documenting (commenting) that you perform within the object template, the more efficiently the object can be used in other projects. Also, the work put into designing the template is paid back in multiples ”the more the object is used in new projects, the higher the payback on the initial investment of development time. Finally, you'll also reduce the chance of something important being missed.

Incorrect:

 '*Settipfile. 

  Const  c_Tip_File="TipOfDay.txt" 

Correct:

 '*NOTE:Changethisconstanttothenameofthetipfile. '*Ifyouprefer,youcanuseavariableinsteadand '*setthevalueatruntime. 

  Const  c_Tip_File="TipOfDay.txt"