Coding Standards

[Stefan Ram]

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.

It might be unrelated, but the Pet 2001 BASIC interpreter
by Microsoft stored the token for »SIN« and similar calls as
»SIN(«. So a programmer had no chance to see »SIN («.

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.

A paean of praise for this:

»I have never, ever, ever seen a great software developer
who does not have amazing attention to detail.

[bells.jpg] I worked with a programmer back in school who
forced anyone working with him to indent using two spaces
instead of tabs. If you gave him code that didn't use two
spaces he would go through it line-by-line and replace
your tabs with his spaces. While the value of tabs is not
even a question, (I've long-chided him for this anal
behavior) his attention to such a small detail has served
him well in his many years designing chips at Intel.«

http://www.softwarebyrob.com/articles/Personality_Traits_of_the_Best_Software_Developers.aspx

 

[Lew]

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.

I would more likely ding you for omitting such spaces. They do enhance
readability.

 

[Matthias Buelow]

I would more likely ding you for omitting such spaces. They do enhance
readability.

No, they don't.</argument_clinic>

 

[Lew]

No, they don't.</argument_clinic>

I made my comment in the first person to acknowledge the subjective nature of
some of these "standards".

 

[Matthias Buelow]

An argument is a connected series of statements intended to establish
a definite proposition.

You have to pay me if you want me to continue arguing with you.

 

[Mike Schilling]

I made my comment in the first person to acknowledge the subjective
nature of some of these "standards".

No, you didn't.

 

[Karl Uppiano]

Then you apparently have never implemented any more complicated or
non-intuitive algorithm...

Oh please...

Which are exactly the kind of useless comments that clatter source code.
I thought the code should be expressive enough without all that chatter?
Documenting trivial details is nonsense. You should explain the big
picture in comments and why you did some details the way you did them,
and not verbosely reformulate parts of the source code.

I explan the big picture in the JavaDocs. By keeping methods short, I can
constrain the number of operations to something that can be described in the
JavaDocs. The biggest problem I have in maintaining other people's code
usually involves non-descriptive variable names, unclear purpose of methods,
member variables, parameters, return values and error conditions, which can
all addressed in JavaDocs.

If I have a tricky algorithm that I need inline comments to describe, I take
that as a hint that it should be in it's own method, complete with JavaDocs.
The parameters, return values and exceptions in concert with the JavaDocs,
become self-documenting.

Unfortunately, your approach is typical for many Java (or industrial,
for that matter) programmers.

I am not sure what you mean by this, but I take it perjoratively.

I've seen quite some programs where the programmer said "don't have to
explain the stuff, the source code is obvious", which were basically
unmaintainable.

So have I. But the proof is in the pudding. I have been writing software
professionally since 1986 -- assembly, C, C++, Java and C#. I started doing
JavaDoc-like comments when I was writing in C, and enthusiastically embraced
JavaDocs when I first encountered them. People who have reviewed or
maintained my code have remarked on the quality and maintainability. I do
not say that boastfully -- but only to illustrate that something I am doing
seems to be working.

Perhaps that is why coding is more an art than a cookbook activity. I
suppose someone else could follow my recipe and end up with garbage.

 

[Matthias Buelow]

Perhaps that is why coding is more an art than a cookbook activity.

I think it is.

Of course, "software-engineering" people have a totally different
opinion on that.

They're wrong.

 

[Martin Gregorie]

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

There are a number of more or less acceptable ways of formatting code,
but there's only one rule that a maintenance programmer should obey:

You WILL use the same indentation and naming rules as the
original author no matter how abhorrent they may see to you.

I've seen far to much code turned into an unreadable dogs dinner by so
called "programmers" failed to obey this rule.

 

[Joshua Cranmer]

(More or less in response to the entire thread)

How ironic it is that no one has written a file system that can
transparently convert between different formats, so that person A would see:

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

and person B sees:
if (foo) {
...
} else {
...
}

(note use of tabs).

Heck, they might even make it translate between getFoo, GetFoo, and
get_foo (binary compatibility not guaranteed)!

Hmmm... it would have to involve extensive use of metadata (so that
FORTRAN files are not formatted as Java files), but if it could be made
relatively painless, it would probably find widespread use...

 

[Karl Uppiano]

This would clash with the "artistic vertical alignment" crowd who like
to put in some extra effort to vertically align things that somehow
belong together in order to make it more readable. This sort of
alignment is notoriously difficult to do automatically (ultimately, it
can't really be done since it depends on rather delicate aesthetic
judgements) and so killing whitespace would not be a reversible
process.

Yeah, I thought about that. It isn't a fully formed idea. I think you could
make compression rules and expansion rules that could take tabs, stand alone
newlines, etc., into consideration. Perhaps I should start a software
company... ;-)

 

[Mike Schilling]

Yeah, I thought about that. It isn't a fully formed idea. I think you
could make compression rules and expansion rules that could take
tabs, stand alone newlines, etc., into consideration. Perhaps I
should start a software company... ;-)

I think you'd want to go further. Define an object model for a Java source
file, and have an engine that renders the object graph according to the
user's preferences. This would make it impossible to save an incorrectly
formed Java file (it wouldn't have to compile, but it would have to follow
at least some of the syntactical rules), or perhaps anything ungrammatical
would be saved as text.

 

[Matthias Buelow]

Heck, they might even make it translate between getFoo, GetFoo, and
get_foo (binary compatibility not guaranteed)!

Actually emacs can do something like that (glasses-mode), it then
displays all CamelCaseIsHardToRead as Camel_Case_Is_Hard_To_Read, which
is a easier to read for some people. While keeping the original style in
the source text, of course. Quite nifty.

 

[=?ISO-8859-1?Q?Arne_Vajh=F8j?=]

I think you'd want to go further. Define an object model for a Java source
file, and have an engine that renders the object graph according to the
user's preferences. This would make it impossible to save an incorrectly
formed Java file (it wouldn't have to compile, but it would have to follow
at least some of the syntactical rules), or perhaps anything ungrammatical
would be saved as text.

Sounds a bit like IBM VAJ.

I would not consider that way a success.

Arne

 

[Roedy Green]

'Good code' is code that works, is bug free, and is readable and
maintainable. Standards need to be followed for coding. Read more...

see http://mindprod.com/jgloss/codingconventions.html

 

[Mike Schilling]

Mike Schilling wrote:

Sounds a bit like IBM VAJ.

That made the mistake of trying to model a Java class instead of a Java
source file.

 

[Patricia Shanahan]

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

I like this style of comment in assembly language code, but dislike it
in high level languages.

If, for example, "cleanUp" really means "close all connections" why not
rename it "closeAllConnections" and remove the comment? A comment that
fits at the end of the line is unlikely to add much to a line of high
level language code with meaningful identifiers.

Patricia

 

[kaldrenon]

I like this style of comment in assembly language code, but dislike it
in high level languages.

If, for example, "cleanUp" really means "close all connections" why not
rename it "closeAllConnections" and remove the comment? A comment that
fits at the end of the line is unlikely to add much to a line of high
level language code with meaningful identifiers.

Patricia

My personal little addition to this advice (with which I otherwise
heartily agree) is that brevity is still nice. Not nice enough to be
worth the sacrifice of meaning, but still nice.

For example, there's no significant difference in clarity between:

closeAllNetworkConnections
closeAllNetConnections
closeAllNetConns (unless you have reason to believe someone might not
recognize the abbreviation of Conns for Connections, but I consider
that common knowledge to a developer)

But IMHO, the last of these three is superior because it's clear what
it means, but it's shorter, which keeps the lines on which it appears
shorter, and is (slightly) less typing. In most examples the
difference is trivial, but once a variable, class, or method name gets
about about 15 characters I start to cringe.

 

[Patrick May]

If, for example, "cleanUp" really means "close all connections" why
not rename it "closeAllConnections" and remove the comment?

[ . . . ]
For example, there's no significant difference in clarity between:

closeAllNetworkConnections
closeAllNetConnections
closeAllNetConns (unless you have reason to believe someone might
not recognize the abbreviation of Conns for Connections, but I
consider that common knowledge to a developer)

But IMHO, the last of these three is superior because it's clear
what it means, but it's shorter, which keeps the lines on which it
appears shorter, and is (slightly) less typing.

I suggest that the first of these is superior because it is very
explicit about the purpose of the method. Programmers reading the
code won't have to mentally expand any abbreviations and programmers
using the method won't have to try to remember which choice of
abbreviations the original programmer made: "Was that
closeAllNetConn(), closeAllNetConns(), closeAllNetworkConns(),
.. . . ."

Regards,

Patrick

 

[Patricia Shanahan]

kaldrenon wrote:
....

For example, there's no significant difference in clarity between:

closeAllNetworkConnections
closeAllNetConnections
closeAllNetConns (unless you have reason to believe someone might not
recognize the abbreviation of Conns for Connections, but I consider
that common knowledge to a developer)

But IMHO, the last of these three is superior because it's clear what
it means, but it's shorter, which keeps the lines on which it appears
shorter, and is (slightly) less typing. In most examples the
difference is trivial, but once a variable, class, or method name gets
about about 15 characters I start to cringe.

I agree with this if, and only if, "conns" is consistently used for
"connections" in identifiers throughout.

Patricia