<- previous index next ->
First: Brandt Braunschweig brandtb1@umbc.edu has an opertunity for you.
The Good, The Bad, and The Ugly
Some sample requirements that may be in a style guide:
(These may vary widely based on language.)
1) There must be exactly one space before every semicolon.
2) Indentation must be exactly four spaces for each
structure. e.g. function, loop, if, exception.
3) There must be exactly one space on each side of
every operator symbol. Exceptions include "++" and "--".
4) Structured programming must be used. Every code block
must have one entrance at top and one exit at bottom.
5) The "go to" statement must not be used.
6) Every file must have the standard header with
company copyright, revision history, ...
7) No single line shall exceed 79 characters.
8) ... and 10 more pages of style requirements.
A significant question is:
Is requiring software engineers to follow a
style guide while writing code, cost effective?
The components of "cost effective" include:
1) average cost per thousand lines of code, $/KSLOC
2) average defect density per KSLOC
3) psychological ramifications, motivation, demotivation
Personally, from my experience, having over a million
lines of code I have written, on my computer,
the answer is no.
The next significant question is:
Is requiring that all software, that goes into every
software product, a company produces, conform to
the companies style guide cost effective?
The components of "cost effective" include:
1) average cost per thousand lines of code, $/KSLOC
2) average defect density per KSLOC
3) average cost of maintenance, defect correction, per KSLOC
4) average cost of upgrades, next version release, per KSLOC
Personally, from my experience, 25 years as a software
engineering manager, the answer is yes.
The person or people doing the maintenance or upgrades will
often be different from the original writer. Thus, having
a consistent style will make these tasks more cost effective.
If source code is delivered to customers, the customer
should not see different styles across all modules.
Some, possibly most, software products have incurred less
than half their final cost upon initial use or delivery.
With a formal development process, checking code against
a style guide would take place as a software quality
assurance review, prior to the software being entered
into the software configuration management system.
This apparent conundrum can and has been resolved.
One best practice at this time in software development is:
1) Software engineers compose source code
directly on a keyboard, into the computer.
2) For each 15 to 30 lines typed, compile and
fix the syntax and semantic errors found
by the compiler. Most compilers provide the
line numbers and most editors can go to
a specified line number. Some editors do checks
some syntax checking while code is being typed.
3) For each module, create a small test driver,
to do a basic check that a normal case will run
4) Run a style formatter program, that inputs
source code and outputs source code that
precisely follows the style guide
5) Possibly add more code, such as checking for
consistent or valid input. Using style guide.
6) Possibly add more tests for bad or consistent
input and more difficult test cases
7) Submit source code and test code and test
results to software quality assurance organization.
Fix defects and repeat until accepted.
8) Submit source code and test code to configuration
management system.
9) Modules are combined into subsystems and subsystems
are combined into the product using similar steps.
The style guide enforcing formatter is re-run
after any significant change.
Some items that may, or may not, be considered "style" are:
1) Use meaningful or descriptive names for variables.
2) Use upper case or underscore to separate multiple
words in a variable name.
3) No variable name may be greater than 24 characters.
4) Use standard loop variables i, j, k, ii, jj, kk, etc
5) The Cyclomatic Complexity Metric must not be greater
than 10 in any module.
6) Each block of code must have a comment, indicating
the purpose or function of the block of code.
7) Every method must operate only on its own object.
Some sample code from Numerical Computation course:
Found in a program that operated on three dimensional structures:
/* initialize A matrix */
for(i=1; i<nx-1; i++)
{
for(ii=1; ii<ny-1; ii++)
{
for(iii=1; iii<nz-1; iii++)
{
for(j=1; j<nx-1; j++)
{
for(jj=1; jj<ny-1; jj++)
{
for(jjj=1; jjj<nz-1; jjj++)
{
/* code here */
} /* jjj */
} /* jj */
} /* j */
} /* iii */
} /* ii */
} /* i */
Then eventually expanded to four, five, six dimensions
/* initialize A matrix */
for(i=1; i<nx-1; i++)
{
for(ii=1; ii<ny-1; ii++)
{
for(iii=1; iii<nz-1; iii++)
{
for(iiii=1; iiii<nu-1; iiii++)
{
for(iiiii=1; iiiii<nv-1; iiiii++)
{
for(iiiiii=1; iiiiii<nw-1; iiiiii++)
{
for(j=1; j<nx-1; j++)
{
for(jj=1; jj<ny-1; jj++)
{
for(jjj=1; jjj<nz-1; jjj++)
{
for(jjjj=1; jjjj<nu-1; jjjj++)
{
for(jjjjj=1; jjjjj<nv-1; jjjjj++)
{
for(jjjjjj=1; jjjjjj<nw-1; jjjjjj++)
{
/* code here */
} /* jjjjjj */
} /* jjjjj */
} /* jjjj */
} /* jjj */
} /* jj */
} /* j */
} /* iiiiii */
} /* iiiii */
} /* iiii */
} /* iii */
} /* ii */
} /* i */
Yes, 12 levels of indentation
This caused a style guide to modify a rule to:
2) Each file shall have consistent indentation.
Indentation may be 2, 3, or 4 spaces.
Having "{" and "}" line up was a violation, yet helped
readability. Some style guides advocate minimizing
the number of lines. There can be gamesmanship when
measuring metrics. Typically the line count is
non blank, non comment lines. Some may add, more
than one character lines. With these restrictions,
the example above, has only 12 lines and that
may be representative of lines with a potential defect.
Automatic Style Guide Conformance
From a history prospective, there once was a program,
known as "A Pretty Printer" that read source code
for a specific language and printed the program
according to a style guide. The first one I saw
was for source code on punched cards in Fortran.
That program was eventually updated to read a
file from disk and write the source code back
to disk in style guide format.
More Automation
There came a time when Department of defense issued
a requirement that delivered source code must be
supplied with a "Flow Diagram" for every module.
The new software engineers were assigned the
documentation task of taking the source code,
that was about to be delivered, and drawing
the flow diagrams. There were specific military
standards on shapes of boxes in the flow diagrams.
The flow diagrams had to exactly match the
source code. Thus, a standard template was used
to draw the flow diagrams on graph paper.
I assigned a software engineer in my section,
to make a program that read source code and
drove our flat bed plotter to draw flow diagrams.
It worked great, and we delivered to DoD the
required flow diagrams. Soon after, DoD deleted
the requirement for flow diagrams.
I hope all style guides get automated
Almost all software metric measurement has
been automated. Computers are much better at
counting and organizing than people.
We still face the management statement:
"If you can not measure it, you can not manage it!"
Homework 2 is assigned
<- previous index next ->