The Code Is The Design

danielread writes "In 1992 C++ Journal published an essay by Jack W. Reeves called 'What Is Software Design?' Many credit this essay as being the first published instance of assertions such as 'programming is not about building software; programming is about designing software' and 'it is cheaper and simpler to just build the design and test it than to do anything else'. developer.* Magazine has republished this groundbreaking essay, plus two previously unpublished essays, under the title Code as Design: Three Essays by Jack W. Reeves."

Comments

False Economy

[Doc Ruby]

It's cheaper and simpler for the initial programmer. After that, we have to spend time (and therefore money) decoding the original code, recognizing idiosyncracies, and retrofitting to work with other code. Even if it's the same programmer, a couple of years later. C++ is more "self documenting" than most languages, when coded properly. And it certainly seemed like the remedy to C, back in 1992 when that screed was written, and C++ was just beginning to be adopted by mainstream programmers. But there's no substitute for writing the requirements, feature definitions, scopes and dependencies first, then the comments in the code blocks, then the code, and tar'ing those docs with the source code. The initial hump is steeper, but the total area under the work curve, over the product lifecycle, is much less.

Re:False Economy

[nagora]

C++ is more "self documenting" than most languages, when coded properly.

That's what they all say. Every language is self documenting when "coded properly". C++ failed in part because of the unfounded belief that its supporters had in its abilities, all of which resided not in the language itself but in the programmer's ability to "code properly". Sadly, there is nothing in the language to enforce such coding practice and it is as rare in C++ as any language.

TWW

I agree completely

[MCTFB]

There are many styles to writing code, but I think that if you are verbose with the naming of your variables, as opposed to naming your variables with unintelligible abbreviations, then that goes a long way to long term code maintenance.

Well written code should read like a book and only need commenting for blocks of code which are not completely obvious as to what their intent happens to be (for example some hack you write up to get around a bug in a library you are using at the time).

One of the most annoying things is the fact I choose not to use an IDE, so developer documentation inserted into the code to describe a function or class or whatever just clutters up the reading of the actual code.

Furthermore, most of the developer documentation of your typical programmer is such that all it describes is the arguments a function takes and what is supposed to be returned, while doing nothing to explain the purpose of the function and why it might be used. In other words, most of the time documentation is useless and just gets in the way because it doesn't relate to anything which makes sense (for humans to understand something new, usually you need to relate it to something they already understand).

So as a general rule of thumb, if you can read the code out loud (or in your head) and you don't constantly have to stop to analyze the code to see what the context of some variable happens to be at any given time, then you are doing a good job. If on the other hand your code cannot be read out loud (because of inaudible variable names), then the odds are some other programmer is going to have to review every other line of your code just to try and make sense of it all.

An ex-employee of mine who I didn't audit very well, spent a ton of time documenting his code in some of the most anally-retentive ways. However, his code just never had any flow. To date, I have had to scrap much of what he worked on because his code was not maintainable.

So in essence, if you have poorly written code, then all the documentation in the world won't do much because poorly written code makes your design inflexible and hard to work with, while well-written code that you can read like a book usually is simple enough that you can mold it into something more useful later on.

So I agree that the code is the design and the design is the code. You can come up with the most elaborate UML diagram known to man, but if the code has no flow to it, and a whole lot of hacks are needed to implement a rigid design structure, then the design overall in the end is going to suck.

If you are going to do documentation, keep your modules small and do it once you are pretty certain the modules won't be changing much from that point on. If you are uncertain, then it is probably best to just ignore the documentation process until things are more set in stone.

Yet Another Metaphor About Carpenters

[reallocate]

It's always seemed to me that design and coding are more than a bit like buiding a house and using carpentry tools. The world's best carpenter won't build much of a house unless someone's done the design (even if it's just one more 3-bedroom ranch he's built many times before -- that design is imprinted in his memory.)

But, you can't live in a design, so both skills are needed.

In the end, people who stand around and argue that good carpenters don't need designs, or vice versa, miss their completion date and lose the customer.

Re:Oh Boy.

[museumpeace]

You are trolling but there are much better educated responses than your taunt deserves.
Well, I am no UML monkey and I have seen software development process overdone so badly even the lowliest coder had rigor mortis. But let me share a few experiences that may be exceptional but I doubt it.

1. I have actually worked with a programmer-turned-project-lead who often stated exactly the premise of TFA as a defense of his designs. He also used design reviews and other people's UML as target practice for a particularly nasty and apparently insecure dismissiveness. He was one of the most brilliant coders I ever met. He understood many programming principles better than others but had a pathological aversion to sharing insight. He was utter hell to work with, poison for the work and the workers in the team. His designs ultimately foundered when noone but him could extend or maintain them.
2. Though language and architecture are not completely seperable, its a shitty design that can't be expressed in any thing but some particular language...saying UML or flowcharts or whatever gets in your way is just a huge hint that you don't know how to express your idea or you don't really have an idea.
3. There is not much argument about the proclivities of programmers: they don't read other peoples code, not often enough, not with sufficient comprehension, not unless they are paid to maintain it. That is a generalization of course but with way too few exceptions. Comments, as others will surely point out, are more important for the longevity of code than the code itself. But commenting that can stand in for requirements and specifications? Virtually nonexistent, there is less of that than there is of good UML. I have been to the long, expensive funerals of way too many programs and sometimes, the companies that were built upon those programs to have much respect for an aproach to software that de-emphasises visibility of the big ideas and critical commonalities in code. Those are aspects that good design documents capture. Those are what make real software, software that can be changed by someone other than the author, software that can be quickly re-tooled for another market or a new platform, hang around long enough to make a company some money.

I'd say the great failing of UML or other design languages or symbology is only that it is not tied to code in such a way that code changes back-propagate to the design document. Its just plain hard work to keep design and code on the same page [litterally and figuratively] but that's what you would pay a competant programmer to do. And that's why JavaDoc and its ilk are my preferred solution in this area[ but I can't point you to a solution that completes the higher level documentation job.]