This post continues the theme "Pass names, not values".
Listing 1. Another style of grouping aliases{
const TCHAR WEEKLY_INSTRUCTIONS[] = {"\\\\ServerName\\FolderName\\Instructions.txt"};
const DWORD QUERY_ATTRIBUTES = 0;
const DWORD DO_NOT_SHARE = 0;
const LPSECURITY_ATTRIBUTES HANDLE_CANNOT_BE_INHERITED = NULL;
const DWORD NOT_APPLICABLE = 0;
const HANDLE DO_NOT_USE_TEMPLATE = NULL;
LPCTSTR file_name = WEEKLY_INSTRUCTIONS;
DWORD access_mode = QUERY_ATTRIBUTES;
DWORD share_mode = DO_NOT_SHARE;
LPSECURITY_ATTRIBUTES security_attributes = HANDLE_CANNOT_BE_INHERITED;
DWORD actions_to_take_regarding_file_existence = OPEN_EXISTING;
DWORD attributes_and_flags_or_security_quality_of_service = NOT_APPLICABLE;
HANDLE template_file_supplying_attributes = DO_NOT_USE_TEMPLATE;
HANDLE hFile = ::CreateFile(
file_name, access_mode,
share_mode, security_attributes,
actions_to_take_regarding_file_existence,
attributes_and_flags_or_security_quality_of_service,
template_file_supplying_attributes
);
}First part of the scope defines the aliases for literals:
• application-defined path;
• and operating system values that do not have textual aliases.
Note that aliases are defined as const. Use of const prevents aliases from accidental change by assignment, like
NOT_APPLICABLE = expression;
Second part initializes parameter descriptors. According to safety rule, if the function has the pointer parameter, and does not modify the value of that pointer, the author should declare the pointer as const. The
CreateFile function prototype violates this rule for 4-th parameter, represented in our example by argument security_attributes: according to CreateFile specification, it is an input-only pointer, but it is not declared as const. That looks a little bit odd by contrast with the first parameter file_name: input-only pointer, which is const. Oh, that Win32 API…
Third part of the scope is the function call.
Local aliases to global aliasesSometimes you may want to share a literal between different scopes. The simplest way to share a literal (more precisely, the alias) is to make it the global alias:
const TCHAR WEEKLY_INSTRUCTIONS[] = {"\\\\ServerName\\FolderName\\Instructions.txt"};
// scope 1
{
// ...
LPCTSTR file_name = WEEKLY_INSTRUCTIONS;
// ...
}
// scope 2
{
// ...
LPCTSTR file_name = WEEKLY_INSTRUCTIONS;
// ...
} VisibilityScopes, which reuse the alias, may be parts of the one file, or they may be spread between modules. The alias is
visible from the module, if the use of the alias in the module does not contradict to programming language rules (in other words, if the compiler does not complain that the alias name is unknown). There are several different flavors of global aliases, distinguished by an alias visibility.
Popular flavors of global aliases| Visibility | Header (.h) | Implementation (.cpp) |
|---|
| Module local constant | | const int x = 1; |
|---|
| Shared constant | extern const int y /*= 2*/; | #include "MyHeader.h"
const int y = 2; |
|---|
| Implicitly copied constant | static const int z = 3; | #include "MyHeader.h" |
|---|
Aliases to encapsulated valuesIf words "global variable" scare you, hide literals (and arrays of literals) inside inside
encapsulated values - functions returning constants, like this one:
LPCTSTR WeeklyInstructionsFilePath() throw()
{
return "\\\\ServerName\\FolderName\\Instructions.txt";
}
Compound encapsulated decisionsEncapsulated values are trivial forms of
encapsulated decisions. Encapsulated decisions that are not trivial include at least two parts:
• the function call
• and the preparation of well-known reusable arguments for this call.
Compound encapsulated decisions may use other encapsulated decisions.
The Listing 2, which derives from the Listing 1, shows an example.
Listing 2. Encapsulated file opening.const TCHAR WEEKLY_INSTRUCTIONS[] = {"\\\\ServerName\\FolderName\\Instructions.txt"};
const DWORD QUERY_ATTRIBUTES = 0;
const DWORD DO_NOT_SHARE = 0;
const LPSECURITY_ATTRIBUTES HANDLE_CANNOT_BE_INHERITED = NULL;
const DWORD NOT_APPLICABLE = 0;
const HANDLE DO_NOT_USE_TEMPLATE = NULL;
HANDLE OpenWeeklyInstructionsFileExclusively( DWORD access_mode )
{
LPCTSTR file_name = WEEKLY_INSTRUCTIONS;
DWORD share_mode = DO_NOT_SHARE;
LPSECURITY_ATTRIBUTES security_attributes = HANDLE_CANNOT_BE_INHERITED;
DWORD actions_to_take_regarding_file_existence = OPEN_EXISTING;
DWORD attributes_and_flags_or_security_quality_of_service = NOT_APPLICABLE;
HANDLE template_file_supplying_attributes = DO_NOT_USE_TEMPLATE;
return ::CreateFile(
file_name, access_mode,
share_mode, security_attributes,
actions_to_take_regarding_file_existence,
attributes_and_flags_or_security_quality_of_service,
template_file_supplying_attributes
);
}
HANDLE OpenWeeklyInstructionsForQuery()
{
DWORD access_mode = QUERY_ATTRIBUTES;
return OpenWeeklyInstructionsFileExclusively( access_mode );
}
HANDLE OpenWeeklyInstructionsForRead()
{
DWORD access_mode = GENERIC_READ;
return OpenWeeklyInstructionsFileExclusively( access_mode );
} Encapsulated decisions as design specificationDespite their simplicity, encapsulated decisions are in fact very valuable part of your program: they concentrate your constructive thought. Interestingly, those functions are highly reusable across modules and projects.
Popular flavors of encapsulated decisions| Visibility | Header (.h) | Implementation (.cpp) |
|---|
| Module local function | | int x() throw() { return 1; } |
|---|
| Shared function | int y() throw(); | #include "MyHeader.h"
int y() throw() { return 2; } |
|---|
Implicitly copied function | inline z() throw() { return 3;} | #include "MyHeader.h" |
|---|
Listing 3. Poor man's encapsulated decisionsHANDLE OpenWeeklyInstructionsForQuery()
{
return ::CreateFile(
"\\\\ServerName\\FolderName\\Instructions.txt",
0, 0, NULL, OPEN_EXISTING, 0, NULL
);
}
HANDLE OpenWeeklyInstructionsForRead()
{
return ::CreateFile(
"\\\\ServerName\\FolderName\\Instructions.txt",
GENERIC_READ, 0, NULL, OPEN_EXISTING, 0, NULL
);
}
Cost of typing against the cost of maintenanceWhat is better: 15 lines of the code in the Listing 3 or 36 lines of the code in the Listing 2?
Many people rushing to finish already late project say "Of course, 15 lines - it is shorter!" Indeed, the Listing 3 contains less code than Listing 2. However, the understanding of the Listing 3 requires much more time than typing of 21 explanation lines: you need to refresh in your memory the description of CreateFile (about of 170 lines), then you need to compare implementations of
OpenWeeklyInstructionsForQuery and
OpenWeeklyInstructionsForRead parameter by parameter.
SummaryIf your code contains multiple calls of CreateFile or any other function with literal arguments, think about encapsulating those calls inside product-specific functions having less number of arguments. Use parameter descriptors and aliases inside encapsulated decisions in order to make your code comprehensible.
