Using Project Templates

Directives

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

Object templates should be made as generic as possible. Because 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 Assembly object of the .NET Framework to obtain application-specific data, such as calling System.Reflection.Assembly.GetExecutingAssembly.Location to obtain the path and filename of the application.

  • 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 named 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.

1.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:
picShowPicture.Image = Image.FromFile("c:\temp\Splash.bmp") 
Correct:
' Load the splash screen from the folder in which this application ' is running. picShowPicture.Image = _       Image.FromFile(System.IO.Path.GetDirectoryName( _       System.Reflection.Assembly.GetExecutingAssembly. _       Location) & "\Splash.bmp") 
1.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: Need to change application title when added to a project. Me.Text = "About Application" 
Correct:
' This code always uses the current application name. Me.Text = "About " & _          System.Reflection.Assembly.GetExecutingAssembly.GetName.Name 
1.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 .NET Framework, always pull that information from the framework.

Incorrect:
' NOTE: You must replace X.X.X with the current version of the  '       application when this object is added to a project. lblVersion.Text = "Version X.X.X" 
Correct:
' This code pulls the version information from the assembly. With System.Reflection.Assembly.GetExecutingAssembly.GetName.Version    lblVersion.Text = "Version " & _                      .Major & "." & _                      .Minor & "." & _                      .Revision End With 
1.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 As String 
Correct:
Private m_strUserName As String Public Property UserName() As String    Get       UserName = m_strUserName    End Get    Set(ByVal Value As String)       Return Value    End Set End Property 

1.2 Provide extensive comments and tasks 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. The best way to do this is to add Tasks to the object.

When you begin a comment with the word TODO, Visual Basic .NET automatically adds a new task to the Task List. (See Figure 1-6.)

If you consistently create tasks in all your object templates, you'll reduce the time and effort necessary for objects based on your templates to be integrated into projects. In addition, the more documenting (commenting) that you perform within the object template, the more efficiently the object can be used in other projects. Realize that the work put into designing a 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, by creating tasks, you'll reduce the chance of something important being missed.

Incorrect:
' Set the following constant to your text file. Const c_strTipFile As String = "TipOfDay.txt" 
Correct:
'TODO Set the following constant to your text file. ' By beginning the preceding comment with TODO, the comment ' will appear on the Task List. Const c_strTipFile As String = "TipOfDay.txt" 
Figure 1-6. Comments beginning with TODO are automatically added to the Task List.

graphics/f01ln06.jpg

Note

The Task List must be set to show all tasks or tasks of type Comment, or TODO tasks won't appear in the list.



Practical Standards for Microsoft Visual Basic. NET
Practical Standards for Microsoft Visual Basic .NET (Pro-Developer)
ISBN: 0735613567
EAN: 2147483647
Year: 2005
Pages: 84

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net