Software Engineering (was Re: Java)

Bryan Sant bryan.sant at
Wed Feb 14 15:10:27 MST 2007

On 2/14/07, Michael Brailsford <brailsmt at> wrote:
> 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.
> -Michael
> 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.

I agree with all of your points.  You're preaching to the choir.  I'm
not suggesting that long names are a replacement for proper
documentation.  But descriptive names do help.  My point was that
Java's verbosity doesn't reduce readability it enhances it.  I'm a
professional, I document all of my code.


More information about the PLUG mailing list