Slashdot Mirror
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."
Might be timely to revisit
Six Laws of the New Software
Rock that crushes, Paper & Scissors that don't matter.
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.
Actually there is: Co-evolving the spec documents, comments, and code. Yes it helps a LOT to plan ahead - and it's a must if you want things to have a chance of getting done in any reasonable time. But trying to cast a spec into concrete in advance of coding is a false economy, too. The spec must remain maleable so the internal problems with it that are discovered during the coding phase can be corrected.
The thing there IS no substitute for is documentation separate from the code itself - whether it's a spec document, good comments, or (preferably) both. Self-documenting code is a falacy - because the code only documents what the code does, not what the code SHOULD do. (Grep is a great program. But it's REALLY broken if what you wanted was cat, or ftp.) Testing doesn't check that a program is "right" - only that it matches a spec. If you're trying to verify correctness of someone else's "self-documenting" code the only thing you can test is the complier. B-)
That applies to you trying to test your OWN code later. You are not the same person you were two months - or even two hours - after you wrote it.
Bantam Dominique roosters crow a four-note song. Once you've heard it as "Happy BIRTHday" you can't NOT hear it that way
The idea is that great code resembles a picasso more than a f-16 fighter.
Picasso could not tell people how he did it, or rather people could not understand picasso's explanation.
An F-16 fighter, however, given enough years of schooling, could be explaned in great detail to anyone. This is why, although incredibly complex, there are thousands of F-16s out there. Yet there are only Picasso's picassos.
Likewise a great coder can't really explain how he wrote the great code. He just could. You can see the result, admire it, copy it even. But to apply the same "creative process" to a different problem, you'd have to be the original programmer.
I say this is why great programming is art and bad programming is not. Just like picasso is an artist and the guy who repainted the wall is not. It's because the "creative process" can't be passed on. It has to be self-invented.
Anything Shakespeare is Shakespeare. Nobody else can write Shakespeare, because they don't have the same creative process he did.
You can study Shakespeare, Picasso, Beethoven all your life and never be able to emulate them. Likewise a great coder's code can be copied, but the process that made the code can't be replicated.
"Piter, too, is dead."
In general, when I'm using a language with embedded documentation features (like Java's javadoc, or "doc++" that does exactly the same thing for C++ comments), I prefer to write the specs using the embedded doc tool itself (write out the spec for a java class by writing out the methods as do-nothing stub routines and then describe what they will do by prepending a javadoc comment to them - then when you generate your javadocs, you have the spec - and since they render into HTML, you can actually make the specs with a lot of complex formatting and all that, just the way the bosses like it. Thus my spec is also the skeleton of the code to be filled in. This approach works better, I think, because it makes it easier to keep the spec up to date when you discover a problem during the coding phase that requires a spec change.
Alas, of late I've been dealing with stuff that doesn't have embedded comment docs and so I haven't been able to do that as much.
Don't label something "offtopic" unless you know the topic well enough to tell what's on topic.
man did anyone actually read the damn article?
He's not saying you don't do traditional software design work, or document. He's saying that if you compare the work that a software engineer does, it is equivlant to the design phase of normal engineering, not the manufacturing phase. That the program you deliver, is in essence, a completed "design" not a manufactured "product".
When you roll out and install this "design" in the target environment, this is the step which equates to normal manufacturing.
It's actually pretty insightful.
Upon reading this again... I realize that the Micrsoft Solution Framework really gets at this idea very well, while still being applicable to large projects. It also attempts to protect against "releasing demo code". It heavily advocates early and continuous builds with an ever expanding capability, so that the development is always *technically* at a releasable stage (within reason).
Flame away for mentioning MS in a good light.