Software Engineering (was Re: Java)

Michael Brailsford brailsmt at
Wed Feb 14 14:51:17 MST 2007

My problem with self-documenting code is that most people think their code is self-documented.  You shouldn't confuse long names with well documented code.  Just because you think something is self-documented doesn't mean a lot in 6 months or even tomorrow to your co-worker.  I have heard it said many times that a piece of code is obvious, only to look at it later and see switch statements mixed in with goto's all accessing shared memory in a multi-threaded app, with massive amounts of globals variables.  The variables had nice names though, as did the functions, but the structure and intent of the code was very much not documented.  Bad code gets written in any language, and unfortunately, most of the code in the world is not written to the same standards as that of open source projects.  Java is no exception, I have seen a lot of bad code in Java.  There is no magic bullet.  (Where "bullet" can be any of language, design pattern, pet tool, etc...) 

I guess this isn't really so much a rebuttal of what you said, since you don't say that self-documenting code is a magic bullet.  Still, it should be laid out there very clearly, good engineering practices in software development are sorely lacking.  They get sacrificed at the altar of deadlines.


P.S.  So fine, this turned into a rant on software engineering.  I think BYU does a better job than most universities with teaching good engineering principles, and the program in general seems to be much more rigorous than many colleague's school's CS programs.  At least that is my impression after being in the industry for a few years now.

----- Original Message ----
From: Bryan Sant <bryan.sant at>
To: Provo Linux Users Group Mailing List <plug at>
Sent: Wednesday, February 14, 2007 2:04:35 PM
Subject: Re: Java

On 2/13/07, Shane Hathaway <shane at> wrote:
> Do you also agree, then, that readability is more important than
> shortcuts for writing code?  Eclipse shortcuts help with writing code
> but do not make up for Java's verbosity.
> Shane

Readability is hugely important.  This is why are am a huge fan of the
Java culture, and their tendency to use
veryDescriptiveNamesForVariablesAndMethods.  Long, descriptive names
are a good thing.  Self documenting code is a goal we should all
strive for.  Java's verbosity is a tremendous benefit.

Though java has long-ish key words, Java is verbose mostly because of
the long class and method names used in the standard libraries and by
most developers, however, there is nothing stopping you from using
Java in a terse way.

So, yes, readability is very important.  Java's verbosity improves
ones ability to read Java, and IDE's make the verbosity a non-issue
when writing java.


PLUG:, #utah on
Don't fear the penguin.

More information about the PLUG mailing list