Coding Standards

[Ed Kirwan]

Patricia Shanahan wrote:

There is a school of programming that holds that a feeling that a block
of code within a method needs a comment is a warning that it should have
been a separate method.
....

Patricia

There seems to be a logical conclusion to this which does harbour some
appeal, though I've never tried it myself.

It could be said that a method may contain only one of the following:

i) A set of non-method-calling statements.
ii) A set of method calls.
iii) A single if-then-else statement plus enclosed sets set of method
calls .
iv) A single iteration plus enclosed sets of method calls.
v) A try/catch statement plus enclosed sets of method calls.

There's something pleasantly ... can't-go-lower-ish about it. Like finding
the unsplittable atoms of execution. It even looks a little language-y, and
might lend itself to (a form of meta-) parsing.

It also raises the question of degree. When does a method stand on its own
two feet and when does it shatter into mini-methods? It would be nice to
identify a mathematically describable property whereby we could chart an
entire-class-in-a-method at one end, and an even more rigid method split
than that defined above (say, rewriting (i) to allow a method to hold a
maximum one non-method-calling statement). It would be nice to find where
such a property's differential would hit 0.

 

[Ben Phillips]

It also raises the question of degree. When does a method stand on its own
two feet and when does it shatter into mini-methods? It would be nice to
identify a mathematically describable property whereby we could chart an
entire-class-in-a-method at one end, and an even more rigid method split
than that defined above (say, rewriting (i) to allow a method to hold a
maximum one non-method-calling statement). It would be nice to find where
such a property's differential would hit 0.

You might be interested in googling "cyclomatic complexity". (The second
hit is the Wikipedia article, and is probably the best place to begin.)

 

[Lew]

Yep. An X-term console window defaults to 25 x 80.

I normally edit source with microEmacs or vi, view it with less and
search it with grep, so compatibility with the default window size
matters to me.

The exception probes the rule:

Sometimes if only a semicolon or close-parenthesis,semicolon sequence falls
past the 80-column mark, I'll not wrap it. Console windows and most editors
will wrap it for me, and there is little semantic confusion thereby.

I also indent with spaces, not tabs.

Another trick someone showed me years ago for in-code comments (as opposed to
Javadoc comments) is to start them at some defined position, say, column 45
(1-based). Then you can read down the right side of the source listing and
see comments, down the left side and see code.

Sort of like:
/** Javadoc comments here. */
public void foo()
{
doSomething(); // do a vital thing
cleanUp(); // close all connections
logResults(); // log to system-defined output
fireEvents(); // notify registered listeners
}

Slash-star comments are good to introduce "paragraphs" of code with
"paragraphs" of comment:

/* Initialize all connections.
* Important to log any errors here.
* INFO level used for additional diagnostic information.
*/

Connection cDb = openDbConnection();
Connection cXo = openXConnection();
...

 

[Matthias Buelow]

While I agree with Matthias's points about commenting the more obscure
parts of one's code, I cannot believe that he seriously is against the
use of Javadocs.

Javadoc has advantages and disadvantages. The most prominent advantage
is of course automated generation of reference documentation, however,
I've found that the major disadvantage is that with javadoc comments,
source code tends to get filled with some kind of textual styrofoam.

 

[Matthias Buelow]

You might be interested in googling "cyclomatic complexity".

Software metrics are like Astrology -- interesting but useless.

 

[Mike Schilling]

Another trick someone showed me years ago for in-code comments (as opposed
to Javadoc comments) is to start them at some defined position, say,
column 45 (1-based). Then you can read down the right side of the source
listing and see comments, down the left side and see code.

Sort of like:
/** Javadoc comments here. */
public void foo()
{
doSomething(); // do a vital thing
cleanUp(); // close all connections
logResults(); // log to system-defined output
fireEvents(); // notify registered listeners
}

He had probably been an assembly-langauge programmer; it was very common for
assemblers, especially those which read punched cards, to have fixed fields
for (say) label, operator, operands, and comments, e.g.

start: mov r0 -(sp) push start address
mov r1 -(sp) push size
mov r2 -(sp) push destination address
jsr copy copy block

 

[Ed Kirwan]

Software metrics are like Astrology -- interesting but useless.

I like Robert Martin's quote on metrics, "However,
a metric is not a god; it is merely a measurement against an arbitrary
standard. It is certainly
possible that the standard chosen ... is appropriate only for certain
applications and is not
appropriate for others. It may also be that there are far better metrics
that can be used to measure
the quality of a design."

Metrics certainly have severely limited value.

Calling them, "Useless," however, seems a little harsh. Matthias, I'm
genuinely interested in hearing your experiences with them; it sounds like
you have an interesting story to tell.

Metrics are just the degree to which machines (as opposed to humans)
understand how good code is.

No, scratch that: metrics are just the degree to which a human can tell a
machine how good a piece of code is.

And that's very, very limited.

But it's not nothing.

We can tell machines that there are some things that are easily recognisable
as bad design, no matter what the scenario.

For example, circular dependencies.

Machines are great at finding circular dependencies, humans aren't (that's
why we create them).

And just because a design has circular dependencies doesn't mean that it is
rubbish (most popular projects on sourceforge have circular dependencies);
but I've not yet come across a programmer who said that a good design
should have circular dependencies.

OT: I've just started using KNode as my newsreader. It highlights
misspellings as I type them. I know that's nothing new, but after coming
from my old newsreader, it feels like wonderful magic. (Cue someone
pointing out misspellings in this post.)

PS I like the way you capitalised, "Astrology;" it sort of lends that art a
degree of respect against which that the rest of your mail railed, and gave
your post a nice, literary tension.

PPS I wonder whether OTs should come before PSs in the grand scheme of
letter-writing (of which newsgroup posts are the latest incarnation).

PPPS Can we also use OOT and OOOT in our posts?

PPPPS Or would OTT be more appropriate than OOT?

PPPPPS Oh, dear, Matthias, you may have just spawned an industry:
computational astrology: the predictions of the success of a piece of
software based on when it was written. I see my Fractality tool (began
24/02/2004, around 8pmish) is a Pisces, which means it's, "Imaginative and
sensitive, Compassionate and kind, Selfless and unworldly, Intuitive and
sympathetic." Good, then it's not, "Riddled with heinous bugs and doomed to
misinterpret Java 6 bytecode for which it's still not updated to parse."

 

[Lew]

PPS I wonder whether OTs should come before PSs in the grand scheme of
letter-writing (of which newsgroup posts are the latest incarnation).

PPPS Can we also use OOT and OOOT in our posts?

PPPPS Or would OTT be more appropriate than OOT?

The reason for "PP...PS" is that the "P" stands for "post", meaning "after",
so it's "after after after after .... after script".

Likewise, you would not say "off topic topic topic ... topic" but "off off off
.... off topic" (like "off-off-off Broadway"), hence, "OOO...OT".

 

[Patrick May]

• each line of code should contain 70 characters max.

Where the **** does that come from?

Legibility. Newspapers are a good example. The reason they use
multiple columns is because humans can only easily scan a limited
number of characters on a single line.

The established standard of between 72 and 80 characters is close
enough to the ideal that there is no good reason to violate it.

Regards,

Patrick

 

[~kurt]

Where the **** does that come from? 1970's? We just inherited shitty

And if it does, what is the problem? Really, what have we accomplished
since the late 60's that is really of any worth? They had some smart
people back then.

code from an outsourcing company where each line fucking wraps around
after some 50-100 characters for no reason. I have a fucking 21 inch

Some of us like to have multiple edit windows open and viewable at the
same time, on the same screen. People who don't wrap at or near FORTRAN
standards should be shot.

Anyway nice try to get some ad revenue. One web page with three layers
of google advertising.

I'm not clicking on it.

- Kurt

 

[Martin Gregorie]

I'm sorry for being a bit dim, Martin, but it's been a long day and it's now
7-minutes-to-beer-o'clock: what do you mean by, "Inline," here?

Comments placed ahead of the statements they describe and indented to
the same level as the statements, e.g.

/**
* Method description.
*/
public void method()
{
statement;
statement;

/*
A comment about the next few statements
*/
statement;
statement;
if (blahblah)
{
/*
A comment about this branch
*/
statement;
....
}
}

and so on. Before anybody jumps in, yes I'm with Lew on the indenting
convention: I find

header
{
.....
}

much easier to read than

header {
.....
}

 

[Martin Gregorie]

I also indent with spaces, not tabs.

So do I, for one good reason: most OSen[1] don't allow you to specify
the length of a tab. Most source editors (vi, microEmacs, PFE, ....) do,
but changing the tab spacing causes them to use spaces instead.

The near universal standard tab space of 8 characters is way too long -
3 or 4 characters is about right.

[1] Microware's OS-9 is the honorable exception: tab spacing is
configurable at the terminal driver level and can be retrieved by any
program that needs to know what it is. The OS-9 default tab spacing is 4
characters - a sensible value.

 

[Joshua Cranmer]

and so on. Before anybody jumps in, yes I'm with Lew on the indenting
convention: I find

header
{
.....
}

much easier to read than

header {
.....
}

But that means you have to do this:

if
{
...
}
else
{
...
}

It was those if/else statements that convinced me to switch to brackets
on the same line.

 

[Joshua Cranmer]

You might be interested in googling "cyclomatic complexity". (The second
hit is the Wikipedia article, and is probably the best place to begin.)

I have never placed much stock in cyclomatic complexity. Ten branches is
way too few for anything even mildly complex. A lexer will probably
easily breach 30 or so; a parser for something as simple as CSS would
probably take 40+. Here's the big finale: a switch statement on a Java
bytecode instruction. It's atomic and gives a cyclomatic complexity well
beyond 100.

 

[Patrick May]

But that means you have to do this:

if
{
...
}
else
{
...
}

It was those if/else statements that convinced me to switch to
brackets on the same line.

That's why I prefer the old Whitesmith format:

if (foo)
{
. . .
}
else
{
. . .
}

Lining the braces up with the block they delimit seems logical. I
also don't put braces around single statements -- I've never had a bug
related to that because Emacs indents everything appropriately for me.

Incidentally, I've heard several times of a study done by NASA
that demonstrated a statistically significant lower defect rate in
code that formatted with braces on their own lines than in code that
uses the K & R style. I'd like to see that study, if it's not an
urban legend from the style wars.

Regards,

Patrick

 

[Martin Gregorie]

But that means you have to do this:

if
{
...
}
else
{
...
}

It was those if/else statements that convinced me to switch to brackets
on the same line.

Sure, but its only two lines more than

if (a) {
blah;
.....
}
else {
blather;
......
}

and that's more difficult to read when you're looking for bracket
mismatches. At least it is for me, but ymmv.

 

[Stefan Ram]

Sure, but its only two lines more than
if (a) {

For completeness, my style:

I write short if-statements on a single line,
preferably without unnecessary braces:

if( a )b();

This might be influenced by my general style rule:

»When two notations have the same meaning,
in doubt, choose the one that is shorter.«

Line breaks are added so as to respect the
syntactical structure. The if-statement's syntax is:

»if ( Expression ) Statement«

http://java.sun.com/docs/books/jls/third_edition/html/statements.html#14.9

The following line break would not respect this:

.----------- break between »if ( Expression )« and »Statement«
v
if( a ) {
^
'--------- line break
b(); ...

This disrespects »well-structured programming«
according to my definition of that term:

»A formal text is well-structured
if its surface structure matches its deep structure
as close as possible.«

Above, the surface structure (line breaks) is misleading
about the deep structure (syntactical breaks).

Therefore, it looks ugly to me, and I break like:

if( a ) // if ( Expression )
{ b(); } // Statement

When there are multiple lines in the block:

if( a )
{ b();
c(); }

Sometimes, I want to put the braces on a line for
themselves to add additional vertical space for
readability. If I have to force each braces on a line,
I write:

if( a )
{
b();
c();
}

Here, one sees, that I do not align matching braces.

I feel the first brace »{« to be still part of the outer block,
because it transfers the control to the inner block like a
method call, which is still part of the calling block.

Conversely, the last brace »}« transfers control back
to the caller, like a return statement. So it is indented
with the inner block.

This is also consistent with a one-pass indenter, that can
change indentation only /after/ it has read a character. The
»{« changes the indentation by 2, the »} by -2, but only after
it was already encountered. So the change becomes visible at
the line break following the indentation-changing symbol for
the first time.

 

[Mike Schilling]

I also indent with spaces, not tabs.

So do I, for one good reason: most OSen[1] don't allow you to specify
the length of a tab. Most source editors (vi, microEmacs, PFE, ....)
do, but changing the tab spacing causes them to use spaces instead.

Or to mix tabs and spaces (4 spaces for one level, a tab for two levels,
etc.). If you're working in a team, it makes far more sense to use spaces
than to insist everyone use an editor that treats tabs identically.

 

[Matthias Buelow]

Calling them, "Useless," however, seems a little harsh. Matthias, I'm
genuinely interested in hearing your experiences with them; it sounds like
you have an interesting story to tell.

First, we have to clarify what kind of "Software Metrics" exist:
structural metrics on procedural code, of Halstead's "Software
Science" kind, like for example the "cyclomatic complexity" that has
been mentioned. object-oriented metrics for computing certain class
properties, and (attempts at) semantic metrics, which actually try to
extract something sensible from the source.

Structural metrics are really banal -- despite their promising names,
they essentially boil down to one thing: larger and more complicated
code is harder to understand. They don't really make any more
complicated statements. The "cyclomatic complexity", despite its
intriguing formula, is essentially just counting the 'if's. The most
primitive metric, LOC (lines of code) is the only one which is
actually in wider use. Others, like the "program volume V*", are, as
one researcher on semantic metrics (Baumann, 1991) said, "completely
chaotic". There is no indication that they actually measure anything
useful.

Object-oriented metrics measure things like the depth of an
inheritance tree, number of children of a class, some weighted
counting of methods per class, coupling between classes according to
certain properties, etc., also relatively simple measurements. Like
conventional structural metrics, they are measuring very superficial
properties of the source code and have no insight into what the
program is actually doing (or supposed to do). Some software managers
say that they have a certain significance but I'm doubtful. At best,
they can indicate some very superficial problems with the code.

A more sophisticated approach are semantic metrics, which try to infer
some kind of semantical "information content" from the source by
applying a theory of semantic and informational areas (with domain
theory). However, last time I looked, there haven't really been any
practical results, maybe there are now.

Machines are great at finding circular dependencies, humans aren't (that's
why we create them).

I'm not opposed to program analyzers in general. I'm just realistic
about the well-known "software metrics" (typically Halstead's
"software science", OO metrics by Chidamber & Kemerer, Briand,
Devanbu, Melo etc.), which routinely get rehashed in software tools
where they are being praised as powerful and indispensable development
aids (by those who sell the software), whereas in truth they are just
primitive, dated (Halstead's stuff is from the 70ies) and rather
arbitrary measurements with very little, if any, practical
significance.

PS I like the way you capitalised, "Astrology;" it sort of lends that art a
degree of respect against which that the rest of your mail railed, and gave
your post a nice, literary tension.

The reason is probably more profane; since I'm German, I occasionally
capitalize nouns also in English, when I'm being careless.

PPPPPS Oh, dear, Matthias, you may have just spawned an industry:
computational astrology: the predictions of the success of a piece of
software based on when it was written. I see my Fractality tool (began
24/02/2004, around 8pmish) is a Pisces, which means it's, "Imaginative and
sensitive, Compassionate and kind, Selfless and unworldly, Intuitive and
sympathetic." Good, then it's not, "Riddled with heinous bugs and doomed to
misinterpret Java 6 bytecode for which it's still not updated to parse."

Written in the Year of the (Code-) Monkey!

 

[Mark Space]

For completeness, my style:

I write short if-statements on a single line,
preferably without unnecessary braces:

if( a )b();

I notice you are doing something else: leaving white space in between
the parenthesis and the term it encloses. I do this also. I'm not sure
where I picked it up. I think it may have been a group of Ada
programmers I hung around with in college.

But I've also been dinged for it in code reviews. This really frosts
me. Dilbert-like attention to meaningless detail is the bane of
corporate culture.