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."
Here we go.
The UML monkeys are gonna have a fit!
The code is the comments.
sigh. I hope this reads better than the headers and comments I normally struggle through when trying to understand another coder's thoughts.
...unless you're from Redmond, then more is still not enough.
Might be timely to revisit
Six Laws of the New Software
Rock that crushes, Paper & Scissors that don't matter.
Given sufficiently high level languages (as appropriate for the app) this would be true.
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.
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'm supposed to be impressed by this? Ten years to republish an article? What a rag. Why, here on Slashdot, you barely have to wait te--
[sound of post getting modded into oblivion]
Is his thesis useful, actionable in a way that is substantially different than what people were/are doing already?
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
Ha.... Ha.... Ha.... how UN-funny. How UN-original. How UN-inspired.
A comedian you are NOT...
The fact that this idea has been circulating since 1992 shows the fact that the business community hasn't embraced this, and continues to ignore it.
It may be about design, but if the business community is unwilling to change its' current practices to implement this, it will remain an obscure idea (albeit a good one), never coming to fruition!
Attention all planets of the Solar Federation! We have assumed control! - Neil Peart
and can only describe how much i agree with this in utterly banal terms.
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.
; -- the corruption of government starts with its secrets. a truly free people keep no secrets. --
Probably something like this?
5 57799@@>>>BBBGGIIKK"[b]-64;C="C@=::C@@==@=:C@=:C@= :C5""31/513/5131/") :0, I (x,Y/2,X ;y-=S*M ;z-=C*M ;b=x* x/M+ y*y/M+z ,0),b =E, a+(a>b ?-b:b)): -1.0);}Z;W;o ,y,z,k, ;}Q;T; ;n(e,f,g, h,i,j,d,a, b,V){o(0 ,e,f,g,h,i,j,a);d>0w =g-C*M,b=(-2*u-2*v+w)b ,b*=200,b/=(M*M),V=Z,E!=0?(u=-u*M/E,v=-v*M/E,w=-w* M// 2),j-=w*E/(M/2),n(e,f,g,h,i,j,d-1/ =2, U/=2,V=V<22?7: (V<30?1:(V<38?2:(V<44?4:(V==44?6:3)))): 0,T +=V&2?b :0,U+=V &4?b:0) :(d==P?(g+=2 /M,U<M /5?(Q=255-210*U /M,U=255 -720* U/M):(U -=M/5,Q=213-110*U ;t(x,y ,a, b){n(M*J+M *40*(A*x +a)/X/A-M*20,M*K,M ;G+=T;B +=U;++a<A?t(x,y,a,G ; }main(){printf("P6\n%i %i\n255"
X=1024; Y=768; A=3;
J=0;K=-10;L=-7;M=1296;N=36;O=255;P=9;_=1<< 15;E;S;C;D;F(b){E="1""111886:6:??AAF"
"FHHMMOO55
"31/531/53"[b ]-64;S=b<22?9:0;D=2;}I(x,Y,X){Y?(X^=Y,X*X>x?(X^=Y
)):(E=X); }H(x){I(x, _,0);}p;q( c,x,y,z,k,l,m,a, b){F(c
);x-=E*M
*z/M-D*D *M;a=-x *k/M -y*l/M-z *m/M; p=((b=a*a/M-
b)>=0?(I (b*M,_
(c,x,y, z,k,l, m,a){Z=! c? -1:Z;c <44?(q(c,x
l,m,0,0 ),(p> 0&&c!= a&& (p<W ||Z<0) )?(W=
p,Z=c): 0,o(c+ 1, x,y,z, k,l, m,a)):0
U;u;v;w
&&Z>=0? (e+=h*W/M,f+=i*W/M,g+=j*W/M,F(Z),u=e-E*M,v=f-S*M,
/3,H(u*u+v*v+w*w),b/=D,b*=
E):0,E=(h*u+i*v+j*w)/M,h-=u*E/(M/2),i-=v*E/(M
,Z,0,0),Q/=2,T
,Q+=V&1?b
,j=g>0?g/8:g/ 20):0,j >0?(U= j *j/M,Q =255- 250*U/M,T=255
-150*U/M,U=255 -100 *U/M):(U =j*j
/M,T=255-435*U
/M,T=168-113*U / M,U=111 -85*U/M) ),d!=P?(Q/=2,T/=2
,U/=2):0);Q=Q< 0?0: Q>O? O: Q;T=T<0? 0:T>O?O:T;U=U<0?0:
U>O?O:U;}R;G;B
*L-M*30*(A*y+b)/Y/A+M*15,0,M, 0,P, -1,0,0);R+=Q
b):(++b<A?t(x,y,0,b):0);}r(x, y){R=G=B=0;t(x,y,0,0);x<X?(printf("%c%c%c",R/A/A,
/A/A,B/A/A),r(x+1,y)):0;}s(y){r(0,--y?s(y),y:y)
"\n",X,Y);s(Y);}
Courtesy IOCCC:http://www0.us.ioccc.org/2004/gavare.c
An Indian-American Hindu committed to non-violent thought/speech/action alarmed by the global explosion of radical Islam
No, you have described UNIX to a Tee though...
In theory, programming is the abstract representation of thoughts and ideas that are in turn an abstract representation of the real world. All code written is a beatiful articulation of those thoughts and ideas, and the meaning is found inherently "in the pudding."
In practice, the details and meaning are lost in the abstraction. I have spent too many hours trying to determine just WTF a fellow programmer's code is supposed to acomplish.
I will admit I am not the first to start writing lines of code before I ever write a thing on a napkin, whiteboard, or sacrificed trees. But design implied in the code alone will very rarely work in a group! It is almost always a necessity to comment your code, and is at best polite to document the design of your code in some surface manner. Code that is never accompanied by design is hardly maintainable or reusable.
Computers are useless. They can only give answers. --Pablo Picasso
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.
Whenever I bring stuff like this up to the powers that be, their response is basically just, "Shut-up and code." Then conversations like this take place between employees:
Dilbert: I'd quit and become an entrepreneur, but I don't know how they handle such huge risks.
Wally: Denial, probably.
Alice: We got bought by our arch-rival this morning. Their CEO says he plans to be as "humane" as possible.
Dilbert: He sounds nice.
Wally: Maybe we'll get bonuses.
A programmer is a machine for converting coffee into code.
Design importance has a direct relationship to the size/complexity of the system being designed AND the "system" that is designing the system. By that I mean, design is a loose term. Me and my roomate can design better by talking about a general idea, and then sitting down and writing code while making adjustments where needed. This process wouldn't work in most coroporate cube farms where you have varying levels of skill, vision, ability to learn, types of users, and the all knowing PHB. This is a stereotype. I picture them developing a strict design that has to be followed. What is important, no matter what type of design you have in front of you is FLEXIBILITY. That designs needs to be able to change without throwing the whole system off balance. In fact, design should be a process which includes the implementation of itself.
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
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
While it may be true that designing is the most critical part of coding, it's dangerous to equate the code and the design. Because that implies, obviously, that writing code is the same as designing it, so just skip any forethought about design concerns and launch right into the coding.
I will admit to being a project manager, not a developer. And I know that thinking through requirements and design specs is the "eat your vegetables" part of programming, and no one really enjoys it nearly as much as writing code. But I constantly see "code without design" being one the the easiest ways to get code that crashes, throws unidentifiable errors, won't handle valid input, or will produce invalid output.
Good design matters. Good coding matters. They go together, but they're not the same.
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"
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."
You haven't seen my code. Nothing designed about it.
I assume you work for Microsoft?
I think we can keep recursing like this until someone returns 1
Ultimately, I'd agree that "code is design", but that this is an overly simplified view. Looking at "x = y + z" and knowing an addition operation is being performed is one thng, but what do these symbols stand for? Why is the operation being done? How does this fit into the overall function of the software? These questions start to become more difficult and time consuming for a human being to answer without an overall design as a project increases in size and complexity.
For example, I might be able to look at an init script and, sans documentation, quickly understand what's going on to the point that I can understand and modify the script. It's hard to argue that I could use the same process for contributing a patch to say, PostgreSQL. I guess I'm trying to say that the relative efficency of people using different forms of design (either code, or explicit design documentation) is analagous to algorithmic complexity for programs.
For me, I can stare at the ceiling fan and draw bubble diagrams for weeks, and actually have a decent plan ..... for some definition of "decent".
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.
The analogy cuts both ways: in some situations, you want code that, like great art, has great staying power once it has been finished. It is self-contained, exists superbly on its own, and doesn't break.
However, not everyone or everyone's code is in that situation. I do development and maintenence for a company that makes industrial equipment. Our controls software is continually in flux, changing in response to changes in technology, changes in customer requirements, and changes in what management wants out of the product line while keeping as much of the existing code base as possible.
We don't want impenetrable masterpieces. We want easily understood functionality, the ability to bolt in new components with a minimum of hair-tearing now, tomorrow, and 10-15 years into the future. We want reconfigurability within a general framework. We want F-16s, not Picassos.
There's room for both models in the wide universe of programming projects out there; the problems come up when you try and use the wrong one for your particular situation.
Unknown host pong.
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
Good point dude
Oh .... my .... god.
.NET and JavaBeans too.
Take all the the solutions in search of problems and jam them into one big wad of crap.
Wait, you forgot about
I really hope this was a troll. If so I applaud it. If not I shudder at the thought that somebody must be working for your pointy-haird ass.
Take something more tangible like a car design. If you lumped destailed descriptions of all the blueprints for the individual components in a nicely bound document without any overall design schematic how hard would it be for anyone to get an overall picture of how the car would look and feel?
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.
These posts express my own personal views, not those of my employer
it wont be a big wad of crap if you have the language generators as plugins, its all UML, objects, thats the basis for EVERY UML designer, then pick the code you want generated, you dont have to have every language, just what you use.
SO, what do YOU suggest then for a FREE OPENSOURCE UML designer?
I currently use SparxSystems Enterprise Architect but want an opensource free solution. Forget about rational rose, since IBM bought rational the price skyrocketed.
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.
Does any other programmers suffer from the paralysis caused by "design staff"? For every project my company starts, someone inevitably gets assigned the task of "designing it". The result is a bunch of incoherent scribbles, quasi-UML documents and vague ideas that us programmers are expected to work from. When we ask for more detail we get an insufficient answer. When we just go ahead and use our own initiative the design dude will moan that we havn't done it exactly how he wanted us to. The whole time I feel like smacking the design guy in the face and saying "why don't YOU fuckin' code it?"
How we know is more important than what we know.
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.
What do you suggest ROFL telnet and vi or emacs ROFL!!! Im glad you DON'T work for me!
I've not used them (can't stand UML myself), but I've noticed that Eclipse has some UML tools. Try this, for instance.
Again, I have no idea about the quality of the plugin. Just one I've noticed along the way.
Microsoft is to software what Budweiser is to beer.
You obviously do NOT understand UML.
You are the troll here, go back to your bash shell scripting zealot.
He doesn't say what you would do different if you follow this approach though.. at least not that I can tease out of it.
You picked the wrong job if you can't stand UML.
You just proved that the design isn't really the code, not that the code isn't really the design!
I've abandoned my search for truth; now I'm just looking for some useful delusions.
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.
Given sufficiently high level languages (as appropriate for the app) this would be true.
And God said, "Let There Be Light."
God uses a very high level language: four words, and the hard work is done.
-kgj
-kgj
When someone's paying you to write code for a project, it's your job to write code that is maintainable and understandable - and if you can't explain the code in terms a child can understand, YOU don't understand it, either.
Nuff said.....
The coder is the Architect. The compiler is the Carpenter.
I've got to say that I'm quite surprised that this was proposed by someone with no links (AFAIK) to the extreme programming methodology, which is the only field in which I've heard this put forward, and I've got to admit, I was utterly sold as soon as I'd heard the reasoning behind it. ... how great is agile development? :-)
So
But there are *very* few great programmers out there. What do the rest of the programming world do?
There's room for great talent in coding, but if the cost is that the code cannot be maintained that talent itself becomes a business risk.
If your boss can't understand your code, that's not really such an issue. But if you tell your boss that you are the only one who can now, or will ever be able to maintain that code, you will see a very different reaction to the one you seem to be expecting.
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. After all - it's written in a known language (unless you roll your own languages just to code an app). It's not in the realms of Picasso, but more in the realm of engineering.
A final thought - there are many, many projects whose complexity makes the most detailed application or operating system look like a kid's crayon drawing. The engineers behind these projects put massive effort into developing them and making sure that everyone involved is crystal clear on what's going on. These sorts of projects rarely (if ever) fail. They're not art, although some approach it. On those sort of projects, a developer who couldn't explain what they were doing would be lethal, and would be sacked immediately.
Riiiiight.
The cheque is in the mail...
It's like english. You know, the annotated book because the author really went all out and the reader has no fucking clue:
... )
:-)
Ye whimsical faerie of yore
Whence came thee upon me?
Forlorn sit I stilled,
Prey to thy designs.
Now, the author wrote about his helplessness at dealing with his past.
Did he? Or is he instead a mental patient, suffering from paranoid delusions of faerie hauntings? Not knowing anything about the author, would you stake your life on whether you've resolve the ambiguity correctly? If you can't, then it's not good technical documentation.
Technical documentation is not prose. It's direct, it's dry, and it's often dull, but it leaves less up to interpretation.
A more technical "poem" might read:
"My fiance died in a kitchen accident ten years ago. I still think of her every now and then when I sit down to the dinner table, and remember how she used to make it for me. Whenever I do, I just sit there, remembering, unable to think of anything but her."
It's lousy poetry, but it explains more about what memories the author is sad about, what triggers the memories, and the degree to which he is affected by them. In that regard, it's probably better technical writing. Programming, and other works of documentation, are closer to technical writing than they are to prose composition.
I worked for the airline industry for almot three years. I learned an important lesson there: ad-hoc complexity is the enemy of safety. You don't want smart people suddenly trying to improvise clever things.
What you want is smart people to have been methodically clever, and carefully expanded their bright designs out so clearly and obviously that it's clear to even the "lowest common denomiator" that everything works. If you can somehow manage a system that even a six year old can prove correct, then you know your system isn't going to fail. The closer your experts can come to that goal, the more confident they can be that everything is right.
On the other hand, if only the head genius understands the system, it's like a ticking time bomb waiting to off. One day, either the genius will have an off day, or maybe his successor just won't be quite as brilliant, and a critical mistake will get made: and no one else will be smart enough to catch it. If he's lucky, the mistake won't kill anyone...
You can make good code go bad by writing for the least common denominator in your organization (always the worst programmers)
If your best coder can't clearly express themselves in simple terms, then you need to ask "why not"? Coding is most fundamentally about expressing intent: to the compiler (relatively easy), and to the code maintainer (much harder).
It's easy to see what code does. It's harder to see why it does it. If there's a reason that a vetran programmer can't use a basic idiom to express himself, I think he should document the reasons why he felt required to do so, and who the new intended audience for the code is.
Ideally, it should cite sources, if available.
For example:
This code was written for senior programmers with a background in Widget programming. For more information on Widget programming, see Knuth, TOCP Edition MXCLLXXII.
This code is a polyglot implementation of FooBlam's Thrashing Widget Algorithm, modified as detailed below. We get a 57 fold performance improvement by doing it this way, as opposed to the traditional WidgetBending method. The following is a sketch proof of correctness of our new method"
or words to that effect. In general, if you're going to be clever, document how and why you've decided to be clever, so that at least your managers know who to assign to take over that section of code when you win the lottery, quit, or get hit by the bus whilst composing a clever new algorithm.
Managers: You can raise code quality b
Sorry, I work embedded. Without some clue of what the physical interfaces are and are intended to be. Without some way of getting a system's engineer to be able to understand the code's design in the context of the hardware design, electro-mechanical components, etc, the code is useless, probably even dangerous. I'm not saying UML is the answer (actually, I believe it's part of the problem because it leads to lazy, incomplete definitions of the system), but some formal, reviewable (by folks other than other programmers) requirements and design product is crucial to a successful embedded project. Maybe the app engineers have an easier time just making pretty code, or maybe I'm not skilled enough to read-the-minds of the system's engineering folks.
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.
I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature. Hence, my title: "Literate Programming."
Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.
The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other.
The idea is that the code and documentation are written together and that you use a tool to "weave" a document from the source for a human to read and another tool to "tangle" that same source into computer compilable source code.
I've written quite a few large scale C and C++ LP's in my time using the tools Nuweb and Funnelweb. Those programs I wrote are all still in use these many years later and maintained by developers many employment generations removed from me. Since moving into OOAD, I've gotten way from that practice, since the IDE's I use aren't really suited for doing Literate Programming. Maybe it's time to take another look.
I'll be the first to admit to not being a real programmer. But I love to read coding books, and occasionally hack something out.
I read the fine article. According to the Pragmatic Programmers, one of the first principles of good coding is: DRY or Don't Repeat Yourself. In other words there should only be one primary, authoritative version of the data, and all others should reference it.
Now the article seeeemed to be arguing that the source code should be that primary source. The other folks here feel that UML or a design spec of some sort should be the primary source.
Should the code meet the spec or the spec meet the code? The Pragmatics believe that you should have a method for generating code and documentation from the specs. Is this truly doable?
True, but you don't work there anymore. In fact I know very few people who work for the same company for even 10 years. In that time they often work on several different projects. Then the company hits the down side of the cycles and lays them off.
If you want to be stuck working on the same code all day, everyday, code that only you have a hope of understanding, be my guest. I don't want to do that though. I have enough trouble figuring out what I was thinking yesterday when I write readable code, much less intentionally unreadable code.
I can visualize lots of code/processes as UML type
,then perhaps it should be part of an IDE, when you hit NEW PROJECT. Do away with source files and include files and have the whole source in a database with each class in each 'file' or 'table', but do away with files as such, just make em transparent.
diagrams, but I see spending 4hrs drawing some crap as a waste when I could have completed the code by then.
I tend to write my code as nice as possible that even a drunk coder could understand it.
I may code up stuff fast with out UML diags, but if people/others need to maintain it, doing a high level UML or layout diag is easy enough to do on demand. Somethings are sometimes too easy to comprehend so id rather not waste hours doing fancy diagrams putting me to sleep.
Try imaging the UML diag for just IE, I bet theres a high level one, but not one down to each class/logic IF statement.
If UML is soooo important
Liberty freedom are no1, not dicks in suits.
Great quotes about code design over the years:
"Code Design. Huh. What is it good for? Absolutely nothing! Say it again. "
"Code design is stupid , and people are stupid." - culture club
"Code design is a battlefield" - pat bennetar
"She's got Bette Davis' code design" - thingy
"I want to take my big hard code design and shove it right into your code design until you taste it in your code design"
"read my lips, no more code design"
Thank you, now I hope you all code design in code design.
You might recall the play-within-a-play from Midsummer Night's Dream, Pyramus and Thisbe.
This ancient story was written long before Shakespeare's time; one might note, too, the striking similarities that Romeo and Juliet has to it.
I find it hard to not question our favorite playwright's sources of "creativity"... Plagiarism, no. But let's give credit where it's due.
House-building: The wood and glass structure is the design!
Car building: Just slap it together - it's faster and cheaper than actually having an engineering diagram!
Financial planning: Forget about planning for retirement. Just save your money however seems to fit best! Your life's finances *is* the design!
Building a Wintel box: Don't research hardware incompatibilities beforehand - just put the parts together and see which ones work!
I've heard a quote that goes (paraphrased) "if you can't keep the design in your head, you're not qualified to be a developer." I think there's some truth to that.
But there is still a design involved in that theory, and I've worked on a couple projects in which a written, documented design, although probably not necessary (they were relatively-simple (about 5,000-6,000 LoC) projects), still proved to be useful occasionally. Mostly they were there to please management, but nonetheless, they weren't worthless.
Were they worth the time I spent creating the designs? Hard to say...
In general though, I think design documents are useful, if for no other reason than to be able to more-clearly explain what it is you're doing to people who wouldn't otherwise have a clue (read: management, your family, etc.)...
Is Capitalism Good for the Poor?
The fact that this can even be entertained as a rational suggestion is all the evidence necessary to conclude that the software industry is not about providing long term viable solutions to real business problems.
Robust, maintainable, well-behaved software that will stand the tests of time and budget CANNOT be arrived at by a PROGRAMMER. A PROGRAMMER will not acknowledge that there are more meaningful measures of design value than a nice algorithm or the latest industry buzz words.
- Sig this!
I actually met the guy who did the Picasso painting on the WHO head quarters in Geneva. And he was not Picasso.
As it turned out, Picasso could and did provide him with a detailed explanation of what to paint.
I realize this has no real bearing on your actual point, but still...
The billrate is my design. If I can pocket $70/hr doing UML, while some punk jockey H-1B coder monkey gets $20/hr for implementing my design, I'm pretty happy about that. I design, the H-1B codes, one year later I move on while the team gets outsourced to India.
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.
I'm trying to teach myself to set people on fire with my mind... Is it hot in here?
Don't write the documentation and the code in separate platforms.
Doesn't fly well with managements love of chartoons and MS-Office, though.
Alas, the typical development organization is not composed of a bunch of Donald Knuth-s.
[/flog horse="dead"]
Yow! I'm supposed to have a plan?
On the other hand, they won't know how to fix the bugs; They will add several lines of code to kludge the problem when all that was required was to remove a line; They will create side effects which they won't know how to test and therefore create even more bugs. Moron programmers will also cut-and-paste the same lines of codes instead of writing a new function; They will make every method and every attribute public to make sure you can never figure out what the API is; They'll comment out old code instead of removing it so that you can have a history of every line that was ever written into a file; ...
Senior programmers shouldn't have to write "down." I agree that they shouldn't use "clever tricks" either but they shouldn't have to unfold for-loops and stop using callbacks and design patterns just because some moron doesn't understand them.
Also, junior programmers are not moron programmers. Moron programmers remain moron programmers until they leave or until they get promoted.
Be careful! If you keep enough moron programmers around, your junior programmers will tend to program like the morons.
The code is the design is just as worse as UML everything to death. What I have found to be the best approach is something in between: Just use a regular word processor to write a document stating the intentions of the program and for any complex data types the reason they are there and how they interact.
Simple, and it doesn't cost a lot of time. Do most of it upfront, and you have already thought out most of your design. Implement it, notice that you need to modify it slightly and just update the documentation accordingly.
I have found that using this approach almost anybody can understand what is happening in a program. Not to mention yourself when you revisit the code after a half year break.
Please login to access my lawn
i've alwyas maintained that if you can't code anythign yourself, then your going to suck with anything like UML or or design software. it's the same mistake managment makes. sitting up there completely oblivous to what's really happening or how things are actually done
If you mod me down, I will become more powerful than you can imagine....
I have been saying this for years, I too met with much derision from my colleagues when trying to explain the concept that code is design. When a computer takes actions based upon 'the design' it becomes the embodiment of that design, an 'implementation'. Many programmers are confused that unlike other more persistent embodiments of design such as a piece of wood that has been carved into the shape of a penguin a computer can implement many different designs, and with a multi-tasking OS can give the illusion of implementing them all at the same time.
The industry needs better tools to manipulate and modify the design (er..code) and better programmers who have an aptitude for writing good designs (um..code).
This leads to another argument that language wars happen due to the importance of language in design and that what we are really arguing about is which language is the best to design systems with and of couse that all depends upon what type of system you are trying to design!
Seems slashdot has keen on propogating pointless coding arguments, that just keep on keeping on.. glad to help out using up data space, on pointless topics..
As an off-topic aside, he won't be "Sir William", but rather "William Gates KBE". In today's enlightened global family, you're only allowed to be "Sir" if you're from a Commonwealth nation. Go figure.
If you disagree, post your argument. (-1, Overrated) isn't your personal censorship tool for views you don't like.
Lately, I've been taking your technique one step further.
During design meetings, I code up the interfaces (Java) and maybe some abstract classes to tie things together. Code, even non-functional code, gives a good validation of the design. Its also easier for other developers and myself to visualize the design with code.
If anything is unclear, or we debate some detail, its easy enough to write some simple implementation classes to test these ideas.
A benefit of this technique, it ensures everyone is coding to interfaces instead of classes. This keeps the code simpler and easier to test. At dev time, you just have the developers grab an interface and implement. No one gets assigned to a task that they are not starting immediately. If we bring in other resources, they don't need to understand the whole project. They can simply work on a component.
At the end of the meetings we reverse engineer (using the tool in WSAD) the interfaces and abstract classes into UML diagrams for the PHB's. I've found most UML tools slow and unwieldly to use. For me anyway, its just much faster to code a skeleton and generate diagrams from it.
----- If communism is a system where the government owns business, what do you call a system where business owns govern
Blockquoth the AC:
If that's a problem for you, either your programming language or your knowledge of it is insufficient. Learn to use destructors/finally blocks/macros (real ones)/whatever the resource management idiom is in your programming language of choice.
Many modern systems need this sort of architecture whether you allow explicit early returns or not, because of the potential effects of exceptions, parallel processing, etc.
If you disagree, post your argument. (-1, Overrated) isn't your personal censorship tool for views you don't like.
there are thousands of F-16s out there.
And there are more than thousands of running Linux kernels other there. The point of TFA is that you can build a new program any time. Just copy the executable. The source is a design for that executable.
Imagine describing the F-16 to "anybody", and expecting them to come up with the design for a new fighter jet. That's the equivalent of describing the source, and expecting its techniques to be applied in a new program. You'd have to be some kind of engineering Picasso to do that.
My Karma: ran over your Dogma
StrawberryFrog
Sure but look at how many bugs were generated.
"Those aren't bugs -- those are features."
-kgj
-kgj
I have yet to see any programming language that can capture design concepts. Eiffel is probably closest. For every other programming language, the design would have to go into comments.
Patrick Doyle
I mod down every jackass who puts his moderation policy in his sig. Oh, wait a sec....
My Website (bear with me, it is still a work in progress...)
My website