Coding Standards

[davidsamith]

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

http://brsx.co.uk/SWtesting/FAQs/FAQs012.asp

 

[Karl Uppiano]

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

http://brsx.co.uk/SWtesting/FAQs/FAQs012.asp

He goes on to write

"...but everyone has different ideas about what's best, or what is too many
or too few rules."

and therein lies the problem.

For example, my code tends to be completely devoid of comments (because I
find them distracting interspersed with the code -- the code itself should
be expressive enough without all that chatter) -- except for JavaDocs, which
I write copiously. It gives me a nice place to describe the class, member
variable, or method, with the input parameters, return values and exceptions
thrown, in a way that is far more structured than you would get with ad-hoc
comments. In fact, if I find myself writing a comment inline with the code
(often justifying something that is just "too cool"), it is usually an
indication that my implementation is flawed.

I tend to keep my methods rather short (less than a screenful). It makes it
easier to document and understand what is going on, and helps to modularize
the operations. That is just my style developed over 25 years of programming
professionally. I developed a "JavaDoc" style of commenting my code when I
was developing in C. I don't expect everyone to follow my style.

As for whitespace and bracket alignment, I often thought that repositories
should delete all extra whitespace, and editors should expand it back
according to individual developer preferences. That hasn't happened yet.

 

[Bent C Dalager]

As for whitespace and bracket alignment, I often thought that repositories
should delete all extra whitespace, and editors should expand it back
according to individual developer preferences. That hasn't happened yet.

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.

Cheers
Bent D

 

[Sanjay]

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

http://brsx.co.uk/SWtesting/FAQs/FAQs012.asp

• each line of code should contain 70 characters max.

Where the **** does that come from? 1970's? We just inherited shitty
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
monitor and so does other developers and there is no one else going to
look at the code besides developers why wrap around 70 characters?

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

 

[Wildemar Wildenburger]

• each line of code should contain 70 characters max.

Where the **** does that come from? 1970's? We just inherited shitty
code from an outsourcing company where each line fucking wraps around
after some 50-100 characters for no reason.
>

Dude, you kiss your mother with that mouth? Whats wrong?

I have a fucking 21 inch monitor
>

Really? I'd hate that, a monitor that constantly fucks me ... and at 21
inches you're bound to feel it too. *sigh* To each his own.

and so does other developers and there is no one else going to
look at the code besides developers why wrap around 70 characters?

1. It looks nicer if all lines have about the same length.
2. It makes it easier to grasp what's in the line.
3. Some people *do* still work in text terminals, you know.

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

Ah, a good point, finally.

/W

 

[Jeff Higgins]

Dude, you kiss your mother with that mouth? Whats wrong?

Thanks for the picture, greatly appreciated.
JH

 

[Lew]

Thanks for the picture, greatly appreciated.
JH

Java already has coding standards (although I always willfully violate them by
putting the opening brace on its own line, aligned with the control statement):
<http://java.sun.com/docs/codeconv/index.html>

I endorse line-wrap at 80.

 

[Joshua Cranmer]

• each line of code should contain 70 characters max.

Where the **** does that come from? 1970's? We just inherited shitty
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
monitor and so does other developers and there is no one else going to
look at the code besides developers why wrap around 70 characters?

Right now, I am stuck with a 1024x768 resolution, so anything more than
~90 characters starts wrapping around. Obviously, you have never tried
to edit a line of code in vim that has wrapped around 3-4 times.

I do, however, agree that 70 characters is too short for a reasonable
line; 80-90 characters is a better limit.

 

[Matthias Buelow]

For example, my code tends to be completely devoid of comments (because I
find them distracting interspersed with the code -- the code itself should
be expressive enough without all that chatter)

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

-- except for JavaDocs, which
I write copiously. It gives me a nice place to describe the class, member
variable, or method, with the input parameters, return values and exceptions
thrown, in a way that is far more structured than you would get with ad-hoc
comments.

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.

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

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.

 

[Matthias Buelow]

Where the **** does that come from? 1970's? We just inherited shitty
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
monitor and so does other developers and there is no one else going to
look at the code besides developers why wrap around 70 characters?

I think it's a good idea not to make stuff "too wide". That doesn't mean
to slavishly stick to a certain columns limit, though. Use some common
sense and aesthetics (most people don't seen to have a sense for this,
though.)

 

[Lew]

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.

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. Javadocs are critical in Java source. They serve double duty - not
only do they help future users of a class to use it correctly, they cover most
of the non-trivial comments one would make about a class or method (or other
exposed member). It's hardly "chatter".

 

[Sanjay]

Dude, you kiss your mother with that mouth? Whats wrong?

Lets keep my and your mother out of this. You stick to the things I am
talking about and don't mention my mother again. Thank you.

 

[Sanjay]

Right now, I am stuck with a 1024x768 resolution, so anything more than
~90 characters starts wrapping around. Obviously, you have never tried
to edit a line of code in vim that has wrapped around 3-4 times.

I do, however, agree that 70 characters is too short for a reasonable
line; 80-90 characters is a better limit.

Of course I use vi or vim or pico or nano whenever I am working on
solaris terminal writing or debugging shell scripts (I use kate or
Quanta on linux). However I have never used vi for writing J2EE code.
For that I always use either eclipse or WSAD depending on the
application server.

I guess I can safely assume we are talking about java or jEE here rather
than shell script. If you are saying you are writing Java code in vi you
seriously have to upgrade to some IDE in order to make your life
easier. That is of course IMHO.

 

[Thomas Fritsch]

Lets keep my and your mother out of this. You stick to the things I am
talking about and don't mention my mother again. Thank you.

Sanjay,
remember, it was you who started to use lots of aggressive and
derogative words. (See the quoted lines above.)
Wildemar Wildenburger just replied in a way similar to yours.

I understand that you have bad emotions about your inherited code. But
be aware: writing with strong emotions probably causes replies with the
same strong emotions.
So calm down, stick to the things, talk about the facts in an
appropriate way, and you will get the polite answers you want.

 

[Patricia Shanahan]

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

Or he may have put each non-intuitive algorithm in its own method, and
included the algorithm outline and reference to its background in the
Javadoc comment.

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.

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.

That strategy works well if the program is small enough for every
programmer working on it to read the whole program.

However, a lot of my work has been on programs with hundreds of
thousands to millions of lines of source code. Often, all I care about
is what a particular function is supposed to do and how it should be
used. I love it when all that information is grouped in a comment at the
start.

Depending on the source code to be self-documenting can lead to a nasty
recursive process. "Recursive" both in the technical sense and in the
sense of causing repetitive cursing on the part of the reader.

Suppose I'm reading A, and notice it may pass a null pointer to B. Is
that OK or a bug? Without a detailed Javadoc comment, or equivalent, I
have to read B to see what it does with null pointers. But B passes the
pointer to C. Now I need to know how C deals with null pointers...

Patricia

 

[Martin Gregorie]

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. Javadocs are critical in Java source. They serve
double duty - not only do they help future users of a class to use it
correctly, they cover most of the non-trivial comments one would make
about a class or method (or other exposed member). It's hardly "chatter".

I've been experimenting with writing class specifications as ASCII text
files structured as:

Introductory text describing the class and its intended purpose,
limitations, etc.

repeat for all constructors
Constructor description
constructor header
end-repeat

repeat for all public or protected methods
Method description
method header
end-repeat

so that, once I'm happy that the spec is complete, correct,
spell-checked and readable it can be turned into self-documented
compilable code by adding:

- the class header and block
- turning descriptions into Javadoc comments and inserting HTML
formatting tags etc
- adding minimal blocks behind the constructor and method headers.

Once this has been done its easy to add implementing code and private
methods.

So far its worked out pretty well, resulting in Javadoc output that
reads nicely and manages to avoid the creation of separate documentation
that must be maintained (but never is).

I agree with Lew about commenting the code: if a method is just inline
statements then the method description is all that's needed, but more
complex code can benefit from having descriptive comments dropped into
it. These are always indented to match the code and use /* ... */
delimiters (never /**) because I don't think that this type of comment
has any place in the Javadoc method description.

 

[Martin Gregorie]

I endorse line-wrap at 80.

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.

 

[Joshua Cranmer]

I guess I can safely assume we are talking about java or jEE here rather
than shell script. If you are saying you are writing Java code in vi you
seriously have to upgrade to some IDE in order to make your life
easier. That is of course IMHO.

Actually, the project I'm referring to is a PHP project that is hosted
on a remote development sandbox server with no GUI access. [*] Second,
I'm using vim and not vi, and I do very heavily use the extensions built
into vim.

[*] Actually, I could open up an X-session tunneling on SSH, but the
computer's slow enough without trying to piggyback on SSH -X session
over another SSH session.

 

[Twisted]

Really? I'd hate that, a monitor that constantly fucks me ... and at 21
inches you're bound to feel it too. *sigh* To each his own.
Ouch...


1. It looks nicer if all lines have about the same length.
2. It makes it easier to grasp what's in the line.
3. Some people *do* still work in text terminals, you know.

Yeah, I know -- those nutters from comp.emacs whose attempted invasion
of this newsgroup I foiled a few weeks ago.

 

[Ed Kirwan]

Martin Gregorie wrote:

....
I agree with Lew about commenting the code: if a method is just inline
statements then the method description is all that's needed, ....

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?