The Code Is The Design 354
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."
I'll Add... (Score:4, Insightful)
boiler plates (Score:2, Insightful)
Re:I'll Add... (Score:2, Insightful)
Re:Oh Boy. (Score:0, Insightful)
ideally this would be true (Score:2, Insightful)
While we are at it, the comments are not needed either (there should be a compiler warning for them).
(not completely joking)
In practice languages are too low level no matter what you use or have "leaky abstractions" which cause problems.
Regardless of whether this guy is right or not (Score:2, Insightful)
False Economy (Score:5, Insightful)
A nice quote (Score:5, Insightful)
> 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 wholeheartedly and utterly agree. (Score:2, Insightful)
code is design.
take any programming language, whatever virtue, whatever failure, it does not matter. the fact that it is a language at all, proves it.
because any single language exists solely and uniquely by and for design. language is for designing things, and describing the design of things to other people, over a process called 'time'.
design implies persistence, and as we all know, time destroys all things. language is design over time, and the multitude languages of mankind, even that of his machines, exists to design things.
i mean to say, this is a language truth, not just a computer programming truth.
programming languages, as language, are a designed language used to describe very specific activities.
take any real-life problem, turn it into a virtual machine, design a language around it (or use whatever is there, in the situation being systemized, already), and you have your application done.
language: the worlds most intentionally widely misunderstood subject.
Re:boiler plates (Score:4, Insightful)
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
Re:False Economy (Score:5, Insightful)
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
The blah is the blah.... (Score:4, Insightful)
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.
Re:Less is more (Score:3, Insightful)
Re:I'll Add... (Score:2, Insightful)
Sigh (Score:4, Insightful)
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.
Re:The blah is the blah.... (Score:2, Insightful)
It does - but that phrase seems to be the submitter's invention, at least from a cursory look at the fine article. Reeves's point is much more sublte and interesting:
It may be that he's using "design" in a more classical engineering sense than most of us coders do.
I agree completely (Score:5, Insightful)
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.
13 years later and he's still right (Score:4, Insightful)
Yet Another Metaphor About Carpenters (Score:5, Insightful)
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 (Score:5, Insightful)
Re:ideally this would be true (Score:2, Insightful)
Why is the distinction important? Two reasons, really. One is versatility. You don't want to constrain a design to having just one implementation. It's useful to be able to choose among competing implementations, say for the Java Virtual Machine for example, because implementation tradeoffs tend to have practical, often emergent and unforseen, consequences.
The other is containment, an aspect of modularity. Since errors, including security vulnerabilities, can be expected to arise during both design and implementation, the most basic way to identify and manage them is to separate them during development. No implementation can make up for bad design, not if it's correct with respect to that design anyway, but at least the effects of a bad implementation can be addressed without breaking the design. But only if the two are clearly separated.
Re:Oh Boy. (Score:5, Insightful)
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.
Re:I'll Add... (Score:5, Insightful)
I agree with basic Idea I think (Score:2, Insightful)
Then I start coding, and about 10 lines into it I realize I've got a major flaw in my design that I could seen weeks ago if I'd been coding. So insofar as "The Code is the Design" stands in opposition to and absolutist commitment to "Da all Design First, Code Later" I'm 100% for it. Insofar as it stands in opposition to "Think about what you are going to do, then do it" I'm against it. Design should start out big a fluffy, and implementation should start out small and concrete. So by the end of the project, The Design==The Code, but while you are making it, you better think of designing as something different than coding, or you'll end up having no design at all.
I'm starting to sound like "the panther", so I'm stopping now.
ph34r my 1337 c0d1n9 5ki11z (Score:4, Insightful)
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.
His titles are misleading. (Score:5, Insightful)
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.)
Re:Yet Another Metaphor About Carpenters (Score:3, Insightful)
There are many "levels" of design (Score:3, Insightful)
What if you asked your average customer to work out if they'd like the car based on these ideas?
This is very much like what you're asking business analysts and users to do if you provide a source code listing and nothing more. If I was in charge of a project, and that's what you handed me after I gave you business requirements, I'd seek to have you removed from the project.
I have to agree (Score:3, Insightful)
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.
Re:False Economy (Score:5, Insightful)
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.
Re:Oh Boy. (Score:3, Insightful)
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
Re:False Economy (Score:3, Insightful)
Dictionary attack- how many devs do you know who use the full name rather than an abbreviation? I can't blame them- ppm makes sense and is much easier than parts_per_million. You also have to get devs who can spell (I went through a 6 kloc assembly program misspelling the work caffeine. This word was probably used on about 300 of those lines. Never once had a compiler error, I misspelled it the same way every time- put the i before e. Didn't realise it til I handed it in and the TA pointed it out).
Indentation- changing it once its in is a bad idea, it can hurt CMS systems. I don't mean simple ones like CVS, I mean higher level abilities like out of order removal of changes.
Comment density- is too dense bad, or good? Probably in between, and probably depends on subject matter. I don't want a paragraph on a get function, but complex image quality algorithms deserve them. I won't get the linear algebra its doing without them.
code complexity- I think we need a turing machine again
Lots of nesting/mid function returns: mid function returns are good, its what stops your code from looking like spaghetti to avoid them (avoiding them usually turns into your other dislike here- increased nesting). Lots of nesting- some things need a lot of nesting (or incredibly complex if statements, which may be worse). Telling when is an exception requires a Turing AI again.
Its a basic problem with computers- they can't judge when a rule should be followed and when not. You end up either spending a large amount of time doing pointless things to get the system to like it (a pain in the ass and leads to ugly code and unhappy coders), you get 10 billion warnings from the compiler (leading to real problems getting lost in the noise), or you get rid of the system.
Basicly- stick to the code reviews. Your fellow devs are AIs capable of passing a Turing test. If they can't you have problems in the first place
Re:False Economy (Score:3, Insightful)
Re:Oh Boy. (Score:3, Insightful)
And I maintain that UML is to programmers what bicycles are to fish...
Maybe embedded systems are different (Score:1, Insightful)
BTW: I can but hate reading schematics and VHDL to figure out what that damn FPGA does. Thank g*d for hardware engineers who write down what the registers are, how they work, etc. How do you think the system's engineer (or your QA engineer) feels about having to read your code to figure out what the damn firmware does, let alone what it's supposed to do.
Worked on a project once where I was asked to update a broken power control system. I asked what the system had to do (i.e. what are the requirements and interfaces) and the answer was, "Well, we didn't and don't have time to write requirements and interface definitions down. Why don't you read the existing code to figure that out." Grrr.
Folks, if you're going to do the "code is the design" thing, PLEASE don't write any safety critical software. Thanks.
Re:Yet Another Metaphor About Carpenters (Score:4, Insightful)
I find it funny that you and many other people use Carpentry as a metaphoric model for coding. However, after working as a carpenter for over half a year I have to say that it is appropriate.
The world's best carpenter won't build much of a house unless someone's done the design
Houses are built as a variation on a template for their entire neighborhood. In richer areas, more variation occurs, but then more money is poured into the project. In older areas, the variation in house styles is mainly due to renovation by the various tenets over the years.
Unfortunately, most code written is mostly re-inventing of the wheel at the design and implementation level. Closed source techniques necessitated this for a long time (the highly-copyrighted Numerical Recipes books, anyone?) Open source should change the re-inventing of the wheel, but I still see a lot of people re-inventing the wheel 6 or 7 times out of 10 projects. The 8th and 9th will probably shoehorn in a custom library of crufty utility code they wrote years ago for college homework.
But, you can't live in a design, so both skills are needed.
Never owned a house, have we? People who can't afford to spend a long time in a motel/hotel/vacation-resort will live in half finished (but up to code) houses and use kitchens that are being actively remodeled. Similarly, you can go grab open source projects from sourcefroge.net to do little more that compile and jump right in. If I recall correctly, I had to code a Ethernet driver module for the 1.7 kernel series. No driver existed for my card. My RedHat Linux 5.6 would loose network functionality after the install. I this any different from living in a multi-story house while the bathrooms on the other floors are being built?
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.
A lot causes schedule slippage in both coding and carpentry. Both in carpentry and in programming projects regularly go over schedule. Customers are told that sickness and surprises will cause the schedules to slip on any construction. With programming projects it is hard to tell people that extra, unexpected work is needed. Showing customers the termite damage in a wall is easy, showing the hacks in a networking library is not.
The correct people and only the correct people talk to customers. These people typically are the people or work with the people who do the design. With coders/software-designers being stereotyped as uncouth and kept away from the customer, the design may not reflect reality. When the customer is not aware of what they are asking (i.e. requirements creep) it is easy to tell them that additional carpentry and materials are not free. Management and the Customer seem to think that additional software features are not free. Your customer facing people must know when to say 'No' and when to say 'it will cost THIS much,' not pander to the idea that coder-time is free because the results aren't physical.
With trim and paint to cover errors, you can get away with 'rules of thumb' in carpentry[1]. Some voids are needed to allow for expansion and contraction of joints. Management never seems to understand the need for well-defined APIs or plug-in architectures (let alone security or data integrity.) Plus, the computer is a little less tolerant of taking the software equivalent of power tools to the virtual memory manager.
Come to think of it, carpentry is a very bad model for programming[2].
------
1. Literally a thumb used as a ruler. With the massive non-squareness of some people's idea of a *square wall*
you have to hate the flexibility of wood over long periodic thermal cycling. Here's a hit: like with bad code, a slightly off wall creeps further out of square with t
Re:Oh Boy. (Score:4, Insightful)
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.
Re:That's Just Wrong (Score:4, Insightful)
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.
Re:I'll Add... (Score:3, Insightful)
Comments shouldn't be telling you what the code is doing, they should tell you why it's doing it.
Re:Dangerous.... (Score:4, Insightful)
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.
Software Design Still Hard, News at 11 (Score:3, Insightful)
Over the years, management has attempted to quantify software development. They've pointed to the visible tools of the trade, the flow charts and the UML, and a lot of them have mistaken that for the process of designing software. In fact the only thing that you really need to design software is an understanding of your customer's requirements (Or your requirements) and the know-how to turn that into a working system. Unfortunately that's not quite so easy to quantify, and so most management types ignore those traits in their programmers.
The folks who are always going on about six-sigma and CMM level 5 always seem to be stumped as to why they can't just give a chmpanzee a UML generator and churn out working project after working project. Turns out that despite all efforts, software design still requires you to think about your problem and how to get from where you are to where you want to be. Go figure.
Re:That's Just Wrong (Score:2, Insightful)
Saying that it should just work is great, but what does that mean when an OS is being developed, and what happens if it doesn't just work?
What happens if circumstances change and the code needs to be modified to take a new situation into account?
This philosophy ties the programmer to the code for life. That means you don't get promoted, you don't get to work overseas, you don't get much. And if you leave, the code will be replaced eventually, no matter how perfect it was at the time.
Code is not an eternal thing. It is not timeless. If it were, your point would stand.
I suspect there are a lot of developers on Slashdot who like to think they're artists, and that's why your posts are being modded so highly. You may be the best programmer on the face of the planet, but then your error is in assuming that every other programmer is as good as you.
Art, however, can have the ability to stand apart from Time. A great work of literature, music, painting or physical movement can be enjoyed hundreds of years after it was created. Some are not meant to last that long, and their brevity adds to their enjoyment.
Face it. Code is not timeless. All code will require updating or replacing at some future point. You're setting your code up for removal by writing something that only makes sense to yourself.
Re:I'll Add... (Score:2, Insightful)
This can be dangerous. I once tracked down a nasty bug to a method which had been left as simply "return 0.0" (by someone else)
The really sad thing was that there was also a test program for the code... unfortunately it only checked that f(a) + f(b) = f(a + b) ... which it did of course.
Re:False Economy (Score:3, Insightful)
The nexus here is the inability of people to agree on a level of competency to understand how true Meyers, and your post, are. C++ is not only capable of showing what the code does (duh, it has to) but also reflecting design decisions. The only reason I can understand the people that do not accept this is because of limited understanding or total lack of it.
Given its "hardcore" industrial toughness, C++ is an elegant [and complicated] language; all things considered. Like it or not, it is successful at acheiving its primary goals and then some.
Yes - it has its warts, as well as its beauty. People often show disdain for things they don't understand more times than not by default as opposed to having valid reasons for doing so. Obviously it is not a silver bullet but it is an effective bullet. Boils down to who holds the gun.