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."
The code is the comments.
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.
--
make install -not war
> 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.
The Army reading list
Fair enough, but would that same programmer have produced a decent design anyway? UML, pseudo-code, anything?
In my opinion if their code is disorganised, their design would be too.
Cheers,
Ian
Does this sound a lot like "The Network is the Computer" to anyone?
Stop with the pseudo-clever melodramatic BS already.
Good code following the design is nothing new. Jumping straight into coding without a design document that the WHOLE team AND your clients/users can read however is insane.
I'm all for productive laziness but this is just plain BS.
These posts express my own personal views, not those of my employer
Perhaps slashdot should have a special section for newbies who don't want to do the hard work of creating software and would rather just hack.
Yes, staring at the ceiling can be just as good as playing with UML. But your job is to communicate -- to the team, to the customer, to the poor maintenance programmer -- just what the heck you are trying to accomplish in your code. The "being the smart kid" should be the easy part. The "getting clarity and agreement on scope and solution space" is what they are paying you for.
I've found that it is very hard to communicate to the customer the contents of a switch statmenet using polymorphism. Hence the reasons for layers of abstraction. Model, design, plan at just enough detail that you can communicate and agree on a strategy with all the stakeholders. Then go play with the bits and bytes.
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.
I won't argue the point, as he does a better job than I could, but I whole heartedly agree with his take on the matter. Especially that paragraph in the "new" essay (2nd one of the 3 in the linked page) that makes the analogy about doctors in discussing the "Less Able Programmer" problem.
11*43+456^2
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.
-- Slashdot: When Public Access TV Says "No"
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.
Clean coal harnesses the awesome power of the word 'clean'.
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.
- 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.
- 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.
- 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.]SLASHDOT: news for people who can't concentrate on work or have no life at all and got tired of yelling back at the TV.
Yeah, the code is the documentation and the requirements and the business definition. Of-course it is if you have nothing else. That's what it becomes if noone bothers to update the docs.
Let me tell you something about that. I have worked on way too many projects (including the current one) where this was the case - there was only code, or the docs were so out of date that really, there was only the code. It's horrific in most cases. Certainly there are horror levels but I am serious, it is just freaky.
Do you know what happens to a project without documentation? Let me tell you what happens: the only way someone can maintain it, given strict deadlines and/or budget constraints is by fixing the bugs without actually understanding the design. So your fix becomes just a special rule for a special case and in the worst scenario it is also a fix that only works for a special kind of data. So what happens at the end with such a project? A 30 year old COBOL program situation - too many rules that are not generalized all over the place with all kinds of side-effects. Good luck supporting that shit.
I will take a high level document describing the system any time instead of jumping into the code right away. I prefer to know the components of the system, the main players, where the configurations are, what patterns are used to develop the system before jumping into the code. It is just too damn bad that it does never happen that way.
You can't handle the truth.
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.)
Bantam Dominique roosters crow a four-note song. Once you've heard it as "Happy BIRTHday" you can't NOT hear it that way
We have ISO at my orkplace. The hardware guys have a sequence of steps of design and manufacture that are well laid out. Getting this applied to the software guys has been more difficult.
One allowable thing is to write test apps to check out areas of coding that one isn't familiar with. This mimics the hardware steps of mockups and prototyping.
Recently I wrote a network app for the first time. Once that experimentation/research was done, I had some useful info to add to the Design (text) Doc. Once I had this much done though, when the time came to "develop" (according to ISO) the developing consisted of nothing more than cutting and pasting my test app, and tweaking some parameters.
I've been wondering about this for a while because it didn't seem right, that I must have been doing something wrong, but the article filled in the missing understanding.
Not such a brilliant coder then ehh?
;) The strongest strength anyone can have is realizing their limits and working around or past them. If someone never realizes they are limited they will never grow ;)
The best way I have ever heard someone explain how you can tell of an interface is good is if you look at it and think, "Of course. How else would you do it?". The design is natural and flows well for your average *skilled* programmer. If someone is very taltented but no one else can understand their designs then the code is not maintainable. Code that is not maintainable is not good. Creating unmaintainable code is something BAD programmers do. So you should consider that fella brilliantly BAD
Jeremy
We never found that useful, but what we did do was generate all header and implementation files from the diagrams. To change the class, you changed the diagram and regenrated the files. This way ensured the diagrams accurately reflected the static interdependecies among classes. All the real logic was in the code blocks, of course, which the tool simply copied verbatim from version to version.
Was it useful? I guess so. I'm not sure it was more useful than the same information extracted into in a textual document more like Javadoc though.
Anyways, yeah, you need requirements and specifications too. But don't forget those requirements and specifications are just as buggy as code that's never been compiled or run, because that's exactly what they are - very high level pseudocode, that can't be subjected to the rigor of execution in themselves.
Writing is not a science, it's an art.
You can codify writing like Heinlein, Herbert, Dickens and Rand.
No matter how many average writers you put together in a room, you won't end up with the Dune saga.
Complexity is the enemy of elegance and power.
C, Lisp, python are so popular because they are elegant, simple, and thus powerful.
It's not its complexity that makes a system great, it's its simplicity.
Likewise Shakespeare.
>Coding is not an art. It's a science. No matter how good the code is, it can be taken apart and understood by others.
Likewise Shakespeare, Heinlein, Asimov, etc. Yet still art. Because while you can reduce it to 26 + punctuation, it's the organization in time and space that makes them unique.
Great code just works, and nobody needs to go back and fix it later, because it's never going to be broken.
If it needs to be modified, you say.
I reply, why?
Because it no longer performs the needed business function you say.
I ask: And that means its broken?
You say: No, it means it needs to do something else.
I Reply: You mean, a different function?
Exactly, you beam.
I counter: Follow the Unix Way: Each program does one thing: What you need is another program.
You slouch. You know I am right.
Zen lesson over.
"Piter, too, is dead."
Sweet Jesus! Did you even read the articles linked? For example, this part?
If you're going to misunderstand the guy, you could at least do it in a new and interesting way.
I will admit to being a project manager, not a developer.
Ah, so that's why you feel qualified to give opinions on something you didn't even take the time to do the reading on.