#LyX 1.6.7 created this file. For more info see http://www.lyx.org/
\lyxformat 345
\begin_document
\begin_header
\textclass scrbook
\begin_preamble
\input{preamble.tex}
\end_preamble
\use_default_options true
\language english
\inputencoding utf8
\font_roman lmodern
\font_sans helvet
\font_typewriter courier
\font_default_family default
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100
\graphics default
\float_placement H
\paperfontsize default
\spacing single
\use_hyperref true
\pdf_bookmarks true
\pdf_bookmarksnumbered false
\pdf_bookmarksopen false
\pdf_bookmarksopenlevel 1
\pdf_breaklinks false
\pdf_pdfborder false
\pdf_colorlinks false
\pdf_backref false
\pdf_pdfusetitle true
\papersize letterpaper
\use_geometry false
\use_amsmath 2
\use_esint 1
\cite_engine basic
\use_bibtopic false
\paperorientation portrait
\secnumdepth 2
\tocdepth 2
\paragraph_separation indent
\defskip medskip
\quotes_language english
\papercolumns 1
\papersides 2
\paperpagestyle default
\bullet 0 5 11 -1
\bullet 1 5 24 -1
\bullet 2 0 0 -1
\tracking_changes false
\output_changes false
\author ""
\author ""
\end_header
\begin_body
\begin_layout Standard
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
input{chapter.tex}
\end_layout
\end_inset
\end_layout
\begin_layout Chapter
Naming Conventions
\end_layout
\begin_layout Standard
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
epigraph{Great software requires a fanatical devotion to beauty.
If you look inside good software, you find that parts no one is ever supposed
to see are beautiful too.
I'm not claiming I write great software, but I know that when it comes
to code I behave in a way that would make me eligible for prescription
drugs if I approached everyday life the same way.
It drives me crazy to see code that's badly indented, or that uses ugly
variable names.}{Paul Graham}
\end_layout
\end_inset
\end_layout
\begin_layout Standard
In this chapter:
\end_layout
\begin_layout Itemize
\series bold
Variables and Parameters.
\series default
Convention for names, based loosely on Java conventions.
\end_layout
\begin_layout Itemize
\series bold
Database.
\series default
Describes how to name database schemas, views, functions, and columns.
\end_layout
\begin_layout Itemize
\series bold
Resource Bundles.
\series default
Describes how to organize resource bundle key-value pairs.
\end_layout
\begin_layout Itemize
\series bold
Files.
\series default
Explores how to automated tasks by following some simple file naming suggestion
s.
\end_layout
\begin_layout Section
Variables and Parameters
\end_layout
\begin_layout Standard
Any worthwhile reporting software will provide developers with the means
to perform run-time calculations as well as ways to alter how the report
functions (and what data is returned).
Calculations are performed using variables and changes to the report functional
ity are exposed through parameters.
Generally, there are three types of parameters: input, constant, and system.
The next section provides suggestions for improving variable names.
\end_layout
\begin_layout Standard
The conventions described in the following sections are based on Java coding
standards, which were devised by Sun Microsystems.
\begin_inset Foot
status collapsed
\begin_layout Plain Layout
Sun Microsystems, and therefore Java, was purchased by Oracle.
\end_layout
\end_inset
Class names are Pascal case
\begin_inset Foot
status collapsed
\begin_layout Plain Layout
\family typewriter
BigDecimal
\family default
and
\family typewriter
ConnectionManager
\family default
are two fine examples of Pascal case.
\end_layout
\end_inset
in Java; whereas, variable names are camel case.
\begin_inset Foot
status collapsed
\begin_layout Plain Layout
Both
\family typewriter
authenticationClientId
\family default
and
\family typewriter
destinationRegionId
\family default
in
\begin_inset CommandInset ref
LatexCommand ref
reference "tab:Variable-Name-Comparison"
\end_inset
are written in camel case.
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Never put spaces in variable, parameter, function, or database column names.
\end_layout
\begin_layout Subsection
Meaningful Names
\end_layout
\begin_layout Standard
\begin_inset CommandInset ref
LatexCommand ref
reference "tab:Variable-Name-Comparison"
\end_inset
provides suggestions for improving variable names.
\end_layout
\begin_layout Standard
\begin_inset Float table
wide false
sideways false
status collapsed
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "tab:Variable-Name-Comparison"
\end_inset
Variable Name Comparison
\end_layout
\end_inset
\begin_inset Tabular
<lyxtabular version="3" rows="3" columns="3">
<features>
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0">
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
rowcolor{tableheader}
\backslash
toprule{}
\end_layout
\end_inset
\series bold
Bad Name
\end_layout
\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\series bold
Better Name
\end_layout
\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\series bold
Best Name
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
midrule{}
\end_layout
\end_inset
clientid
\end_layout
\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
authClientId
\end_layout
\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
authenticationClientId
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
r
\end_layout
\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
region
\end_layout
\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
destinationRegionId
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
tabularnewline
\backslash
bottomrule%
\end_layout
\end_inset
\end_layout
\end_inset
</cell>
</row>
</lyxtabular>
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
A variable name of
\shape italic
clientid
\shape default
does not indicate how the variable is used in the query that drives the
report.
A better name offers a clue: the identifier is used to control what data
can be retrieved.
The best name removes all mystery.
A variable name of
\emph on
r
\emph default
is useless; be explicit:
\emph on
region
\emph default
,
\emph on
radians
\emph default
or
\emph on
radius
\emph default
leaves no doubt how the variable is used.
A name of
\shape italic
region
\shape default
improves the situation by providing an indicator of the column that is
likely to be filtered by its value, but the best name, again, eliminates
the mystery.
\end_layout
\begin_layout Standard
In short, be descriptive of intent and avoid uncommon abbreviations.
A few extra seconds of typing will save future report maintainers a few
minutes of head-scratching.
\end_layout
\begin_layout Subsection
Variables
\end_layout
\begin_layout Standard
Variables and input parameters are fairly similar; their value is likely
to differ between separate report runs.
We can give a hint to future report maintainers that the variable has a
calculated value by adhering to the following naming notation:
\end_layout
\begin_layout Itemize
Use camel case (also known as mixed case).
\end_layout
\begin_layout Itemize
Do not begin the word with an uppercase letter.
\end_layout
\begin_layout Subsection
Input Parameters
\end_layout
\begin_layout Standard
Input parameters are values that are supplied by the end user to change
the underlying query in subtle or drastic ways.
A report that provides the user with a way to list all the cities in a
particular region must offer the user an input parameter to select the
region.
Since input parameters are closely related to database column names, there
is a certain symmetry that results when using a similar naming scheme:
\end_layout
\begin_layout Itemize
All lower case.
\end_layout
\begin_layout Itemize
Separate words using underscores.
\end_layout
\begin_layout Subsection
Constant and System Parameters
\end_layout
\begin_layout Standard
Names of constant parameters should provide a clue to anyone maintaining
the report, the values do not change.
Many constant values are already provided, as shown in
\begin_inset CommandInset ref
LatexCommand vref
reference "fig:Parameter-Passing"
\end_inset
.
All of them abide by the following rules:
\end_layout
\begin_layout Itemize
All upper case.
\end_layout
\begin_layout Itemize
Separate words using underscores.
\end_layout
\begin_layout Standard
System parameters can also be considered constants.
The differences are that their values rarely change and are never set by
end users as input.
They should follow the same naming conventions as constant parameters.
\end_layout
\begin_layout Subsection
Convention Summary
\end_layout
\begin_layout Standard
\begin_inset CommandInset ref
LatexCommand ref
reference "tab:Suggested-Naming-Convetions"
\end_inset
lists the recommendations from the previous sections.
If you do not already have standard naming conventions for reports, consider
adopting the standards described in this chapter.
\end_layout
\begin_layout Standard
\begin_inset Float table
wide false
sideways false
status collapsed
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "tab:Suggested-Naming-Convetions"
\end_inset
Suggested Naming Convetions
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Tabular
<lyxtabular version="3" rows="4" columns="3">
<features>
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0">
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
rowcolor{tableheader}
\backslash
toprule{}
\end_layout
\end_inset
\series bold
Report Artefact
\end_layout
\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\series bold
Convention
\end_layout
\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\series bold
Example
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
midrule{}
\end_layout
\end_inset
Variable
\end_layout
\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Camel case
\end_layout
\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\family typewriter
stationId
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Parameter
\end_layout
\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Lower case, with underscores
\end_layout
\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\family typewriter
station_id
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Constant
\end_layout
\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Upper case, with underscores
\end_layout
\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\family typewriter
STATION_ID
\family default
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
tabularnewline
\backslash
bottomrule%
\end_layout
\end_inset
\end_layout
\end_inset
</cell>
</row>
</lyxtabular>
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Section
Database
\end_layout
\begin_layout Standard
Choosing a consistent way to name database objects provides opportunities
to automate tasks, reduces the system learning curve for new developers,
and simplifies SQL statements (thereby increasing productivity and reducing
bugs).
\end_layout
\begin_layout Subsection
Schemas
\end_layout
\begin_layout Standard
In
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
apppostgres{}
\end_layout
\end_inset
, the default schema is called
\family typewriter
public
\family default
.
Do not use it as a catch-all for the database objects you create.
Rather, think about creating a set of schemas that group database objects
in ways that make sense to the business.
Prefix the schemas with an abbreviation to help avoid conflicts.
\begin_inset CommandInset ref
LatexCommand ref
reference "tab:Example-Schema-based-Business"
\end_inset
lists some examples.
\end_layout
\begin_layout Standard
\begin_inset Float table
wide false
sideways false
status collapsed
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "tab:Example-Schema-based-Business"
\end_inset
Example Schema-based Business Areas
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Tabular
<lyxtabular version="3" rows="5" columns="2">
<features>
<column alignment="left" valignment="top" width="0">
<column alignment="left" valignment="top" width="0">
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
rowcolor{tableheader}
\backslash
toprule{}
\end_layout
\end_inset
\series bold
Schema Name
\end_layout
\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\series bold
Purpose
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
midrule{}
\end_layout
\end_inset
\family typewriter
wms_core
\end_layout
\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Common reusable objects (shared by business areas).
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\family typewriter
wms_reports
\end_layout
\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Functions, types, and views that are exclusively report-related.
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\family typewriter
wms_web
\end_layout
\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Supporting functionality used for the web site.
\end_layout
\end_inset
</cell>
</row>
<row>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
\family typewriter
wms_batch
\end_layout
\end_inset
</cell>
<cell alignment="left" valignment="top" usebox="none">
\begin_inset Text
\begin_layout Plain Layout
Objects related to batch processing.
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
tabularnewline
\backslash
bottomrule%
\end_layout
\end_inset
\end_layout
\end_inset
</cell>
</row>
</lyxtabular>
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Separating database objects into appropriate schemas will make it easier
to segregate responsibility and apply a coarse-grained security model.
\end_layout
\begin_layout Subsection
Views
\end_layout
\begin_layout Standard
The
\family typewriter
information_schema
\family default
offers a way to look at database objects in the system.
By using a unique prefix (or suffix) for views that are related to a given
subject area (such as reports), it is simple to extract a complete list.
For example, if all report views started with a prefix of
\family typewriter
report_
\family default
\series bold
,
\series default
then the query in
\begin_inset CommandInset ref
LatexCommand ref
reference "alg:Information-Schema"
\end_inset
would return them all.
\end_layout
\begin_layout Standard
\begin_inset Float algorithm
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename source/sql/information-schema.pgsql.png
display false
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "alg:Information-Schema"
\end_inset
Information Schema
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Some databases have tight limits for the number of characters in object
names, so choose your prefixes carefully.
Consider providing a distinguishing suffix, such as
\family typewriter
_vw
\family default
for views and
\family typewriter
_tbl
\family default
for tables.
\end_layout
\begin_layout Subsection
Functions
\end_layout
\begin_layout Standard
Give clear names to functions to indicate how they are used in the system.
Function names such as
\family typewriter
func100
\family default
convey little meaning.
Names of function parameters should also provide information on how they
are used in the function.
\end_layout
\begin_layout Standard
\begin_inset CommandInset ref
LatexCommand ref
reference "alg:Function-Prototype"
\end_inset
shows a good function prototype.
\end_layout
\begin_layout Standard
\begin_inset Float algorithm
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename source/sql/function-prototype.pgsql.png
display false
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "alg:Function-Prototype"
\end_inset
Function Prototype
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
The
\family typewriter
report_
\family default
prefix indicates that it is a function related to reports.
If all reports are in a schema named
\family typewriter
report
\family default
, then this prefix is not necessary.
If, however, the function (for whatever reason) must reside in the
\family typewriter
public
\family default
schema, which is not recommended, then using a unique prefix will help
identify it as report-centric for future maintainers.
\end_layout
\begin_layout Standard
Comments (not shown) for the function must describe its purpose, detail
what callers of the function must know about the expected values for the
parameters, and declare the meaning of the return value.
\end_layout
\begin_layout Standard
One final note about function parameters: prefix them with
\family typewriter
p_
\family default
followed by the name of the database column (when applicable) that the
parameter will influence or be influenced by.
For example, if the parameter tries to match a city name against the
\family typewriter
city_name
\family default
column, the parameter should have a related name, such as
\family typewriter
p_city_name
\family default
.
\end_layout
\begin_layout Subsection
Types
\end_layout
\begin_layout Standard
Type names should correspond to the data object that uses them.
\end_layout
\begin_layout Standard
\begin_inset CommandInset ref
LatexCommand ref
reference "alg:Example-Database-Type-Name"
\end_inset
shows a data type for the function prototype in
\begin_inset CommandInset ref
LatexCommand ref
reference "alg:Function-Prototype"
\end_inset
.
\end_layout
\begin_layout Standard
\begin_inset Float algorithm
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename source/sql/climate-t_report_city.pgsql.png
display false
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "alg:Example-Database-Type-Name"
\end_inset
Example Database Type Name
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Because the type name corresponds to the data object, it is immediately
obvious that it relates to the
\family typewriter
report_city
\family default
function.
\end_layout
\begin_layout Subsection
Columns
\end_layout
\begin_layout Standard
Column names must adhere to the following guidelines (declared as part of
a table or named within a view):
\end_layout
\begin_layout Itemize
Use underscores instead of spaces.
\end_layout
\begin_layout Itemize
Avoid using keywords.
\end_layout
\begin_layout Itemize
Code column names explicitly.
\end_layout
\begin_layout Itemize
Use the same name for the same data.
\end_layout
\begin_layout Standard
The last point requires good communication between development teams.
It is easy to give different names to data that are exactly equivalent.
For example,
\family typewriter
company
\family default
,
\family typewriter
companyid
\family default
,
\family typewriter
company_id
\family default
,
\family typewriter
clientid
\family default
, and
\family typewriter
client_id
\family default
might be used interchangeably throughout the code base.
If so, rename them as the same identifier:
\family typewriter
company_id
\family default
.
\end_layout
\begin_layout Subsection
Entity Aliases
\end_layout
\begin_layout Standard
Abbreviating aliases for tables and views (entities) in SQL statements is
a common practice.
Entity aliases should have some correlation to the name of the table or
view to which they refer.
\begin_inset CommandInset ref
LatexCommand ref
reference "alg:Entity-Aliases-Bad"
\end_inset
shows a SQL statement that eliminates context.
\end_layout
\begin_layout Standard
\begin_inset Float algorithm
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename source/sql/entity-alias-bad.pgsql.png
display false
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "alg:Entity-Aliases-Bad"
\end_inset
Entity Aliases (Bad)
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
There is little contextual correlation between aliases and entities.
In the above example, it is easy to tell at a glance what aliases are assigned
to what entities (for longer queries, however, this is best avoided).
Plain alphabetical assignment cause aliases to shift in meaning from query
to query.
That is, the alias
\family typewriter
b
\family default
will refer to different entities between different statements, which can
lead to confusion and errors.
Contrast this with a consistent naming scheme shown in
\begin_inset CommandInset ref
LatexCommand ref
reference "alg:Entity-Aliases-Good"
\end_inset
.
\end_layout
\begin_layout Standard
\begin_inset Float algorithm
wide false
sideways false
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename source/sql/entity-alias-good.pgsql.png
display false
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "alg:Entity-Aliases-Good"
\end_inset
Entity Aliases (Good)
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
The names of aliases are based on the first word of the entity that they
represent.
It does not matter what naming scheme is used, as long as it is consistent
and correlates entity aliases to the tables (or views) that they represent.
\end_layout
\begin_layout Section
Resource Bundles
\end_layout
\begin_layout Standard
As mentioned, a resource bundle (also known as a
\emph on
properties file
\emph default
) allows reusing the same text strings throughout all reports.
In practice, property files can grow to be unwieldy and unorganized quite
quickly.
The result is duplicated strings, which ultimately undermines one of the
reasons to use properties files.
\end_layout
\begin_layout Standard
Use resource bundles to provide text for the following:
\end_layout
\begin_layout Itemize
Column names
\end_layout
\begin_layout Itemize
Report titles
\end_layout
\begin_layout Itemize
Header content (for example, company name, parameter labels)
\end_layout
\begin_layout Itemize
Footer (for example, pagination, printed date, copyright)
\end_layout
\begin_layout Itemize
Sidebars
\end_layout
\begin_layout Standard
Resource bundle files can be edited by hand with any text editor or within
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appireport{}
\end_layout
\end_inset
itself.
To edit a new file with
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appireport{}
\end_layout
\end_inset
:
\end_layout
\begin_layout Enumerate
Open a resource bundle file you want to edit (for example,
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
filename{text_en.properties}
\end_layout
\end_inset
).
\end_layout
\begin_layout Enumerate
Type:
\end_layout
\begin_deeper
\begin_layout LyX-Code
property.name=value
\end_layout
\end_deeper
\begin_layout Enumerate
Save the file.
\end_layout
\begin_layout Enumerate
Close the file.
\end_layout
\begin_layout Standard
When you re-open the file, the contents appear as shown in
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:Resource-Bundle-Text-Properties"
\end_inset
.
\end_layout
\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status collapsed
\begin_layout Plain Layout
\begin_inset Graphics
filename captures/ireport-resource-bundle-01.png
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "fig:Resource-Bundle-Text-Properties"
\end_inset
Resource Bundle Text Properties
\end_layout
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
To get the most out of resource bundles, group them logically and use consistent
key names.
For example, consider using a dot-separated notation, such as:
\end_layout
\begin_layout LyX-Code
\family typewriter
domain.subject.specifier=Value
\end_layout
\begin_layout Standard
A project that spans multiple domains (for example, climate and population)
would have the following keys and values:
\end_layout
\begin_layout LyX-Code
\family typewriter
climate.city.station=City Station
\end_layout
\begin_layout LyX-Code
\family typewriter
climate.city.name=City Name
\end_layout
\begin_layout LyX-Code
\family typewriter
population.city.location=City Location
\end_layout
\begin_layout LyX-Code
\family typewriter
population.city.name=City Name
\end_layout
\begin_layout Standard
Manually writing and maintaining resource bundles includes the following
problems:
\end_layout
\begin_layout Itemize
Developers might write their own resource bundles.
\end_layout
\begin_layout Itemize
Column names become inconsistent between reports, and between systems.
\begin_inset Foot
status collapsed
\begin_layout Plain Layout
This defeats one of the main reasons to use resource bundles.
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
Column names and values, that have the same meaning, are duplicated.
\end_layout
\begin_layout Itemize
There is no facility, beyond simple text searching, to query the keys, values,
and column widths.
\begin_inset Foot
status collapsed
\begin_layout Plain Layout
For report developers using Windows,
\begin_inset CommandInset href
LatexCommand href
name "grepWin"
target "http://code.google.com/p/grepwin/downloads/list"
\end_inset
is an invaluable and expedient search tool.
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
Resource bundles are not frail, but are awkward to edit for translation.
\end_layout
\begin_layout Standard
Most of these problems, and others, are resolved in
\begin_inset CommandInset ref
LatexCommand ref
reference "cha:Data-Dictionary"
\end_inset
using a design that maps business areas to database columns.
\end_layout
\begin_layout Section
Files
\end_layout
\begin_layout Standard
Java, environment variables, web browsers, shell scripts, and batch files
do not handle spaces in file names well.
Although great strides have been made in resolving the general problem
(quotes for paths, automatic substitution and interpretation of %20 in
URLs, and enclosing variables in quotes), it is better to avoid spaces
in file names altogether.
\end_layout
\begin_layout Standard
Mandate that any files, or directories, that are checked into the repository
abide by the following simple naming rules:
\end_layout
\begin_layout Itemize
Names may not contain spaces.
\end_layout
\begin_layout Itemize
Names must be all lower case.
\end_layout
\begin_layout Itemize
Names should consist of alpha-numeric characters, with underscores or hyphens
to separate words.
\end_layout
\begin_layout Itemize
Names must not begin with a hyphen.
\end_layout
\begin_layout Section
Summary
\end_layout
\begin_layout Standard
Choosing the right name for something, spending an extra thirty seconds
to think of a reasonably adequate name can save others minutes, even hours,
when they are trying to decipher source code.
A variable named
\family typewriter
r
\family default
offers little insight, little meaning, and little relevancy of its use.
Source code (from SQL queries to
\begin_inset ERT
status collapsed
\begin_layout Plain Layout
\backslash
appr{}
\end_layout
\end_inset
statements and from LaTeX
\begin_inset Foot
status collapsed
\begin_layout Plain Layout
LaTeX is a free, high-quality typesetting system for technical and scientific
documentation.
\end_layout
\end_inset
documents to Java classes) should strive to use variables whose names are
as descriptive as possible.
With C-based languages, it is customary to use shorter names when a variable
has a narrow scope, and longer names when the scope is larger.
In reports, use longer accurate names and stop trying to save a few seconds
of typing.
Consider future report maintainers, including yourself.
\end_layout
\end_body
\end_document