On 2/14/07, Michael Brailsford <[EMAIL PROTECTED]> 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.
-Bryan
/*
PLUG: http://plug.org, #utah on irc.freenode.net
Unsubscribe: http://plug.org/mailman/options/plug
Don't fear the penguin.
*/
