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

I'll Add...

[Sexy Commando]

The code is the comments.

Re:I'll Add...

[DunbarTheInept]

That doesn't fix anything because in general I have observed that the same author who would write impossible to understand code will also write impossible to understand comments that actually mislead you more often than they help you. People who are bad at explaining a precise algorithm's details in an elegant form using Java, C, Perl, or Python are also bad at explaining it in an elegant form using English, for the exact same reasons. They're just not good at communicating carefully and clearly in general.

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

Re:False Economy

[Viking Coder]

I can't read someone else's architectural design. I have no idea how the problem domain works. I have no idea what kinds of generalizations and concepts were used to break the problem down. I have no idea which facets of the problem were important, and which could be ignored. I don't know anything about the material sciences involved. What I don't know could just about fill the Grand Canyon.

Why do you presume that reading a software design (source code) would be any different?

It's hard to read a design - even a good one - until you "get it." Until you grok it. Those other documents you talk about are freaksihly important, and the author doesn't deny that - but they are not the design. They are of fundamental importance to the success of the design, but we shouldn't pretend that they are the design.

You're absolutely right to refer to those things as "documents." They help document. But they are not the design.

He's not saying skip design, he's saying that you do what you have to, in order to think the problem through (some design, some documentation, some testing, etc.), and then you work on the real, actual design (the source code.)

Refering to "the initial programmer" like you do is completely ignoring everything he's saying.

A nice quote

[tcopeland]

> Personally, I think a person with his feet on
> the desk staring at the ceiling can be "doing
> design" just as seriously as someone playing
> with UML diagrams in ROSE.

So true. Although I find it helpful to move along these reveries by writing little test apps to put wheels on some ideas... just little 10-20 liners to help get a better handle on things.

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:boiler plates

[Rei]

Part of the problem with headers and comments is the exact same problem with pseudocode: they're not maintained. If they're wrong, the code program doesn't break. The longer they sit around, the less likely they are to be accurate. That's why self-documenting code is a lot more important. Simple, straightforward functions, long, descriptive variable names and functions, etc. If you have to comment a "section" of a function call with a relatively short but important comment, why not just break that part out into its own function call with a descriptive name similar to the comment that you'd use? It's not like the program will run slower; modern compilers can choose whether to inline functions or not better than programmers can in most cases.

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.]

His titles are misleading.

[Ungrounded Lightning]

The article title is misleading.

It makes it sound like he's talking about coding with no forethought and eschewing all documentation (including all comments) in favor of letting the code be the documentation (the "self-documenting code" falacy that has been touted - and known to be false - since at least the early '70s).

What he's actually arguing is that the steps of the process are misnamed - and that this results in mismanagement. The documents currently called the "design" are just requirements and a high-level / overview documentation of early thoughts. The process currently called "coding" is actually most of the design work.

This is recognized in the silicon industry - where CAD tools have evolved the process of "designing a chip" into something virtually identical to "writing an application". But in the silicon industry the nomenclature is still "designers" for "programmers" - and "verification-" or "design assurance-" engineers for "test engineers".

(The latter, by the way, is a highly skilled specialist {in either software or hardware operations} that many software shops don't use, substituting "testers", or confusing them with testers when they happen to have gotten one by mistake. On the "hard side of the force" such people are normally recognized as high-status (and high-pay) pros - the architect's police force and the designers' respected teammates and designated rescuers.)