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.
Might be timely to revisit
Six Laws of the New Software
Rock that crushes, Paper & Scissors that don't matter.
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]
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
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
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.
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.
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
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."
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'.
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
Unknown host pong.
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
man did anyone actually read the damn article?
He's not saying you don't do traditional software design work, or document. He's saying that if you compare the work that a software engineer does, it is equivlant to the design phase of normal engineering, not the manufacturing phase. That the program you deliver, is in essence, a completed "design" not a manufactured "product".
When you roll out and install this "design" in the target environment, this is the step which equates to normal manufacturing.
It's actually pretty insightful.
Upon reading this again... I realize that the Micrsoft Solution Framework really gets at this idea very well, while still being applicable to large projects. It also attempts to protect against "releasing demo code". It heavily advocates early and continuous builds with an ever expanding capability, so that the development is always *technically* at a releasable stage (within reason).
Flame away for mentioning MS in a good light.