|
This article goes back about 2 years before I wrote any code so I wouldn't have originally read it.
It touches on amazing things & really gets to the heart of what _Designing Software_ is actually about and why it is so tough.
What Is Software Design? by Jack W. Reeves - developer.*, Developer Dot Star[^]
Article Length
Our modern sensibilities make this article seem extremely long but much of everything that is really true about Software Design is actually in this article. I'm quite amazed, because I can see that many things grew from this article -- or at least the same kind of thinking as this article.
Summary of Best Points
1) Documentation of any Significant Software Project is necessary.
2) Documentation is always wrong (or will be in 2 minutes when the code is changed).
3) The only true documentation of a Software Project is THE CODE.
-- This is true because the code eventually becomes the instructions to the machine (CPU) and reality of the code is contained in the code itself.
-- Also true because natural language can contain numerous interpretations so that simply reading the documentation may result in X number of individuals understanding that the software _should_ do entirely different things.
4) Since the only True Documentation is in THE CODE, the better the Programming Language, the better it allows you to Design Software. That is where C++ and OOP came in!
5) Suddenly with OOP (via C++) you had a tool that allowed you to create Structures (classes) in Patterns to Design your software which self-documented.
There's a lot more in this article & I encourage you to read it if you are interested in Software Design.
I'm actually going back to read it a 2nd time now.
|
|
|
|
|
I used to get C/C++ User's Journal on a regular basis back in the day. It had many articles of this calibre.
Freedom is the freedom to say that two plus two make four. If that is granted, all else follows.
-- 6079 Smith W.
|
|
|
|
|
I agree with all those points.
Documentation is obsolete as soon as it's written. Documentation also never contains bugs.
But don't forget about SmallTalk and Turbo Pascal as other early OOP languages.
|
|
|
|
|
Thanks for posting. The article was worth reading. Most unusually, it didn't say anything that I'd disagree with.
There are actually three parts to the article: the original (1992), a follow-up (2003), and the letter to the editor that became the original article, and which is very similar.
What really resonated was coding simply being part of design. It's what refactoring and "letting the code speak to you" are about. Detailed design, before writing code, is a waste of time, because the details invariably change, so all that documentation becomes waste. I would even go so far as to say that the code is not only the design, but the primary documentation. There should be a high-level design document as a roadmap. But beyond that, the code must be well commented, because it is the only thing that will document the code at the detailed level. No one will bother to update a parallel, detailed design document. To be usable, it would have to hyperlink to the code fragments being discussed. Even if tools for that existed, I'd rather read plain text comments in the code.
|
|
|
|
|
Greg Utas wrote: I would even go so far as to say that the code is not only the design, but the primary documentation
Absolutely! Code is the documentation. Whenever there is something considered wrong (a bug, etc.) where do people look? Do they look in the docs? Not really. Instead they go to the code to determine what it is doing.
Greg Utas wrote: There should be a high-level design document as a roadmap.
That's how I see it too. A over all plan / road map. You can use the map to get their in many different ways, we just know that your starting here & you must end up there.
The specifics of how you do it will be worked out along the way -- yes with some planning, of course.
As I was reading your comments I was thinking, "hmmm... I would most likely enjoy working with Utas on a project." That made me think that maybe we should force someone we are hiring to read this doc & then ask them their real feelings on it. If they answer similar to you, they are hired. Otherwise...
|
|
|
|
|
If you're hiring someone who will manage your process, then by all means screen them by having them read the article. But if you're hiring a developer, they'll have to use your process anyway, and will probably come around to this way of thinking even if they currently don't believe in it.
|
|
|
|
|
raddevus wrote: Code is the documentation. For the main reason: The developer never wrote anything else.
|
|
|
|
|
this article is great! I will read at least three times...
diligent hands rule....
|
|
|
|
|
Thanks for posting. That article is really & truly amazing because it was written when I was at the start of my career (now 30 years) & it encompasses just about everything that has come & gone in Software Design over those years.
|
|
|
|
|
Microsoft has announced a set of best practices called the Open App Store Principles for its Windows app store and future game console marketplaces. Beware of geeks bearing gifts?
|
|
|
|
|
Quote: Microsoft won’t deliberately rank its own apps over competing ones and will apply consistent, transparent moderation rules In other words, all apps will continue to be equally unfindable in the store.
|
|
|
|
|
|
During the end of 2021 and the start of 2022, DevJobsScanner has analyzed more than 4M dev job offers from around the world to help us understand the market and the most trending and paid languages. With great scarcity comes great pay cheques
Because I never stop sharing randomly-generated lists with you
|
|
|
|
|
Scanner or Scammer? The job openings here say something completely different
Solidity may be high paid, because no senile person earns money on it.
Bastard Programmer from Hell
"If you just follow the bacon Eddy, wherever it leads you, then you won't have to think about politics." -- Some Bell.
|
|
|
|
|
So the point of new languages isn't to make solutions easier but to create scarcity which drives up salaries.
|
|
|
|
|
Some Mazda owners in the Seattle area are stuck with bricked infotainment systems after listening to a particular radio station. Hopefully it's a good radio station
That's...an interesting bug.
|
|
|
|
|
Quote: "These customers should contact their local Mazda dealer, who can submit a goodwill request to the Mazda Warranty department on their behalf, order the parts, and schedule a free repair when the parts arrive," Surprising. The cynic in me says that American brands would have stuck to 'Out of warranty - pay up suckers' as a response to get the $1,500 from them. Of course, that quote doesn't guarantee such also won't be the case for those Mazda owners, but it makes it sound far more likely they will get it fixed without cost.
|
|
|
|
|
This got enough coverage that Mazda may be trying to ward off a NHTSA ordered recall on all Mazda vehicles with that head unit in it.
|
|
|
|
|
Doesn't seem to have much to do with NHTSA, but overreach is a thing nowadays. Besides, it's what they deserve for listening to NPR.
|
|
|
|
|
It's always NPR.
(I sense a fundraising opportunity; send us money or we'll brick your infotainment system. I mean, we'll stop it from happening. This isn't extortion.)
|
|
|
|
|
The Black Hawk is kitted out with Sikorsky Matrix autonomous flying technology. I vaguely recall this movie
Or am I just confounding "Stealth" with "Blue Thunder"?
Either way: "how could this go badly?"
|
|
|
|
|
Yes, Blue Thunder was a manned helicopter, Sheriff Brody got tired of them damned sharks.
I’ve given up trying to be calm. However, I am open to feeling slightly less agitated.
|
|
|
|
|
|
I don’t do creepy, crawly bugs, but software bugs are a different story. I relish the opportunity to hunt and kill particularly nasty software bugs. Step 0: apply for funding
|
|
|
|
|
Open-source software has always been more secure than proprietary software, but that doesn't mean it's "secure." Mo' eyes, mo' dough
|
|
|
|