6 ms·

I wrote a rebuttal of the "blueprints for software" analogy a couple of years ago. http://paulspontifications.blogspot.co.uk/2013/01/software-has-civeng-envy.h

I wrote a rebuttal of the "blueprints for software" analogy a couple of years ago. http://paulspontifications.blogspot.co.uk/2013/01/software-has-civeng-envy.html http://paulspontifications.blogspot.co.uk/2013/01/software-h... TL;DR: Source code is the blueprint for software. However that doesn't mean I completely disagree with Lamport's arguments. Specifications are necessary in large-scale software because otherwise you can't know if you have actually implemented everything the program is supposed to do. When you release it the end-users get angry and insist that they told you in that email / meeting / watercooler conversation last year how important it was that the program frobnicate the warbles. Lamport makes much of formal specifications. I agree that in some cases they do add value; trying to prove the correctness of a distributed protocol in any other way is dumb. But in my experience once you get up into application-level requirements a formal specification is basically source code you don't know how to compile; there is no formal correctness criteria against which you can verify it, and the stakeholders can't understand it in order to verify it.

onion2k 12y ago
The "source code is the blueprint for software" analogy doesn't work because the source only tells you what the application does, not what it's supposed to do. There is no way to tell, from the source code alone, whether or not what's been built is fit for purpose. You have to have some other document. The "specification is the blueprint" analogy is saying that the specification is a high level document that sets out what the application is meant to do. As an example, imagine you're paid $1m to assess my super awesome new database. I give you the source code and tell you "the source is the blueprint." After reading through the code you discover there's no DELETE function. Have I built a clever immutable data store, or am I just an idiot who forgot a critical function? You can't tell that from the source.
- lambeosaurus 12y ago
  I agree with you both. Technically the source is a blueprint. But this comes down to scale. Among other things I've worked on banking and corporate management applications. You cannot reason about the codebase at that scale. In these instances it's not possible to have a good outcome without a blueprint. Using the building metaphor, you can get away with building a bird feeder without a blueprint. You can't get away with building a skyscraper without one. Houses, maybe. Either way, high level blueprints help everyone.
  - br3w5 12y ago
    Good points - I think you need some kind of spec or something to reason about. But I don't think it needs to be complete because it is easier to iterate on software than buildings. Taking the building metaphor, you can't clone a building locally and make changes to it, then ask another builder to review them, suggest some changes then push them out to a test environment before finally putting them into the real world. So for me, the building metaphor only goes so far but there are definitely some useful points in the article.
  - ArekDymalski 12y ago
    > you can get away with building a bird feeder without a blueprint Definitely. But anyway, unless you have built several bird feeders or similar constructions before, your first version will probably be ugly and you'll have to iterate on it (i.e. find the right angles etc.) to make it better. What is of course fun, but costs you time.
- DanielBMarkham 12y ago
  I cannot tell that from the database, sure, because a database is simply structural information, not functional. Without a list of things that the database is supposed to do, it might be great or it might suck. Don't know. But all modern systems have both structure and behavior. For every database there is a MVC model somewhere, for instance. And looking at those controllers, you should absolutely be able to tell whether the database is well-constructed or not. Now there's another consideration: does the database structure map into some problem domain such that the introduction of new controllers will be supported? That's usually what people mean when they talk about architecture: the mapping of a problem domain over to a solution domain such that changes in the requirements have minimal impact on the solution. In System-of-Systems work I'd argue yes, such work has some value -- as long as it is continually driving some kind of delivery (and not just "smart guys drawing boxes"). But in regular green-field system development? Not so much. That's because the tendency is to begin focusing on the wrong thing, the model instead of the user. Timeboxes help with this, so much so that I wouldn't advise any stand-alone architectural work in such an environment without team integration and time-boxing.
- mreiland 12y ago
  The analogy still holds. If I hand you a blueprint for a skyscraper and I realize there is no lock specified for the front doors. Does that mean it's a lockless skyscraper or I'm speaking to a jackass who forgot a critical function related to security? You can't tell from the blueprint. If a specification is required to be 100% complete for all things that could possibly relate in any way, then even blueprints don't qualify.
collyw 12y ago
Yes this is exactly how my organization works, because my team leader is too lazy to spec anything out. Its an absolute nightmare when something doesn't work as expected, because rather than checking a specification that will take a couple of seconds to read, you basically have to debug software, which takes a lot longer.
erikb 12y ago
But the article directly says source code can't be the spec because it contains low level details. E.g. you implement something with map/apply instead of loops because that's all your programming language has, or your filter out some characters from a data stream because they often make a third party parser raise Exceptions you don't understand. These are programming details that the source code contains but the spec shouldn't. Therefore I think your argument is debunked by the main article already. In any case it's a good discussion to have in this thread, which is why I gave you the up.
- marcus_holmes 12y ago
  An Architect's drawing of a building contains every single detail of that house. It's not a high-level sketch of what needs to be built, it's an exhaustive plan for every part of the finished product that has been extensively iterated with the customer to make sure it's correct. Changes to this plan once complete are expensive. So yes, it's exactly like code. But I just wish people would stop comparing software development to construction. They're not alike at all, not even vaguely. Programming is not like bricklaying, because bricklaying is deterministic and uncreative: there is one correct method of laying the bricks, and any two competent bricklayers will lay the bricks in exactly the same way. But there is never one single correct method of writing a program, and no two programmers will implement a feature in the same way. Any attempt to create a specification so exhausting that it allows no deviation by individual programmers should stop pretending it's a spec and just write the damn code. In fact, the author of the article should probably stop writing specs and just iterate prototypes to achieve the same end: there's no difference between "understanding our programming task" in formal English or understanding it in code, except that the code is more useful and a lot easier to test.
  - erikb 12y ago
    There are many points worth of discussion in your comment. I just pick one for now. The details of the architects work. I am no architect, so all I think about it can be true or false. But what I remember from an architect friend is that an architect's work is not really that detailed. It's like the photoshop mockup of a website, not like its source code. It doesn't say exactly which materials should be chosen or how many screws should be used to connect two ends. An architects design says "There is a wall x cm thick and y cm long". The source code says "There z bricks and the last one we had to cut to n cm" (sometimes a comment will state why it had to be cut). For the source code it is to some degree by accident the amount of bricks creates something that can be called a wall.
cam_l 12y ago
I was going to go the other way here and point out that blueprints are actually code for buildings.. the builder is the compiler I guess? But blueprints are done at various scales and they differ in complexity and format ie. sketches, models, schedules. They also often come with a book of specifications, and these are typically only referred to when ordering parts or if something goes wrong - and they are always open to interpretation..
maxPwrWgt 12y ago
"TL;DR: Source code is the blueprint for software." ...and the 2x4s are the blueprint of a house and the steel beams are the blueprint of the skyscraper.... I'll take the TL;DR at face value since it was written by the author. The statement completely obliterates the entire concept of a blueprint or plan. By that reasoning, it is true everything is its own blueprint, and the concept has no meaning (of course this is a standard tautology). And, simply nodding to CYA documents (for when the customers/end users come back saying that your product doesn't do X), or to docs for when formal proofs are needed, doesn't cover the concept. The point of planning (or blueprinting) is to think about what you are going to build before you get out the tools, abstracted away from the specific tools that you'll use, and to then record and communicate those thoughts to all the stakeholders. It doesn't have to be a complete formal, engraved-in-stone blueprint, but a modest amount of actual thinking and planning goes a loooong way. I've often found that with a little thought, we'll use a different tool than originally expected. If you expect to just dive in and sort it out in your source code, then you've already a priori restricted your choice of tool, and probably also your library, algorithm, etc. (of course if you only have or know one tool then, well, 'everything looks like a nail and who needs a blueprint?'). Without planning, you'll get what grows out of the first thing that comes to mind, not the best thing you could build. The mere fact that it manages to run or stand is not a defense of the bad process. Planning is where the real thinking takes place. Sure, if all you want to do is exercise your programming skills and avoid thinking, then don't plan. But don't pretend that no one else should think or plan, or complain when someone else presents a plan to which you are expected to build (and don't be surprised 10 years on when you don't advance as far as you expected).

onion2k 12y ago

The "source code is the blueprint for software" analogy doesn't work because the source only tells you what the application does, not what it's supposed to do. There is no way to tell, from the source code alone, whether or not what's been built is fit for purpose. You have to have some other document. The "specification is the blueprint" analogy is saying that the specification is a high level document that sets out what the application is meant to do. As an example, imagine you're paid $1m to assess my super awesome new database. I give you the source code and tell you "the source is the blueprint." After reading through the code you discover there's no DELETE function. Have I built a clever immutable data store, or am I just an idiot who forgot a critical function? You can't tell that from the source.

lambeosaurus 12y ago
I agree with you both. Technically the source is a blueprint. But this comes down to scale. Among other things I've worked on banking and corporate management applications. You cannot reason about the codebase at that scale. In these instances it's not possible to have a good outcome without a blueprint. Using the building metaphor, you can get away with building a bird feeder without a blueprint. You can't get away with building a skyscraper without one. Houses, maybe. Either way, high level blueprints help everyone.
- br3w5 12y ago
  Good points - I think you need some kind of spec or something to reason about. But I don't think it needs to be complete because it is easier to iterate on software than buildings. Taking the building metaphor, you can't clone a building locally and make changes to it, then ask another builder to review them, suggest some changes then push them out to a test environment before finally putting them into the real world. So for me, the building metaphor only goes so far but there are definitely some useful points in the article.
- ArekDymalski 12y ago
  > you can get away with building a bird feeder without a blueprint Definitely. But anyway, unless you have built several bird feeders or similar constructions before, your first version will probably be ugly and you'll have to iterate on it (i.e. find the right angles etc.) to make it better. What is of course fun, but costs you time.
DanielBMarkham 12y ago
I cannot tell that from the database, sure, because a database is simply structural information, not functional. Without a list of things that the database is supposed to do, it might be great or it might suck. Don't know. But all modern systems have both structure and behavior. For every database there is a MVC model somewhere, for instance. And looking at those controllers, you should absolutely be able to tell whether the database is well-constructed or not. Now there's another consideration: does the database structure map into some problem domain such that the introduction of new controllers will be supported? That's usually what people mean when they talk about architecture: the mapping of a problem domain over to a solution domain such that changes in the requirements have minimal impact on the solution. In System-of-Systems work I'd argue yes, such work has some value -- as long as it is continually driving some kind of delivery (and not just "smart guys drawing boxes"). But in regular green-field system development? Not so much. That's because the tendency is to begin focusing on the wrong thing, the model instead of the user. Timeboxes help with this, so much so that I wouldn't advise any stand-alone architectural work in such an environment without team integration and time-boxing.
mreiland 12y ago
The analogy still holds. If I hand you a blueprint for a skyscraper and I realize there is no lock specified for the front doors. Does that mean it's a lockless skyscraper or I'm speaking to a jackass who forgot a critical function related to security? You can't tell from the blueprint. If a specification is required to be 100% complete for all things that could possibly relate in any way, then even blueprints don't qualify.

collyw 12y ago

Yes this is exactly how my organization works, because my team leader is too lazy to spec anything out. Its an absolute nightmare when something doesn't work as expected, because rather than checking a specification that will take a couple of seconds to read, you basically have to debug software, which takes a lot longer.

erikb 12y ago

But the article directly says source code can't be the spec because it contains low level details. E.g. you implement something with map/apply instead of loops because that's all your programming language has, or your filter out some characters from a data stream because they often make a third party parser raise Exceptions you don't understand. These are programming details that the source code contains but the spec shouldn't. Therefore I think your argument is debunked by the main article already. In any case it's a good discussion to have in this thread, which is why I gave you the up.

marcus_holmes 12y ago
An Architect's drawing of a building contains every single detail of that house. It's not a high-level sketch of what needs to be built, it's an exhaustive plan for every part of the finished product that has been extensively iterated with the customer to make sure it's correct. Changes to this plan once complete are expensive. So yes, it's exactly like code. But I just wish people would stop comparing software development to construction. They're not alike at all, not even vaguely. Programming is not like bricklaying, because bricklaying is deterministic and uncreative: there is one correct method of laying the bricks, and any two competent bricklayers will lay the bricks in exactly the same way. But there is never one single correct method of writing a program, and no two programmers will implement a feature in the same way. Any attempt to create a specification so exhausting that it allows no deviation by individual programmers should stop pretending it's a spec and just write the damn code. In fact, the author of the article should probably stop writing specs and just iterate prototypes to achieve the same end: there's no difference between "understanding our programming task" in formal English or understanding it in code, except that the code is more useful and a lot easier to test.
- erikb 12y ago
  There are many points worth of discussion in your comment. I just pick one for now. The details of the architects work. I am no architect, so all I think about it can be true or false. But what I remember from an architect friend is that an architect's work is not really that detailed. It's like the photoshop mockup of a website, not like its source code. It doesn't say exactly which materials should be chosen or how many screws should be used to connect two ends. An architects design says "There is a wall x cm thick and y cm long". The source code says "There z bricks and the last one we had to cut to n cm" (sometimes a comment will state why it had to be cut). For the source code it is to some degree by accident the amount of bricks creates something that can be called a wall.

cam_l 12y ago

I was going to go the other way here and point out that blueprints are actually code for buildings.. the builder is the compiler I guess? But blueprints are done at various scales and they differ in complexity and format ie. sketches, models, schedules. They also often come with a book of specifications, and these are typically only referred to when ordering parts or if something goes wrong - and they are always open to interpretation..

maxPwrWgt 12y ago

"TL;DR: Source code is the blueprint for software." ...and the 2x4s are the blueprint of a house and the steel beams are the blueprint of the skyscraper.... I'll take the TL;DR at face value since it was written by the author. The statement completely obliterates the entire concept of a blueprint or plan. By that reasoning, it is true everything is its own blueprint, and the concept has no meaning (of course this is a standard tautology). And, simply nodding to CYA documents (for when the customers/end users come back saying that your product doesn't do X), or to docs for when formal proofs are needed, doesn't cover the concept. The point of planning (or blueprinting) is to think about what you are going to build before you get out the tools, abstracted away from the specific tools that you'll use, and to then record and communicate those thoughts to all the stakeholders. It doesn't have to be a complete formal, engraved-in-stone blueprint, but a modest amount of actual thinking and planning goes a loooong way. I've often found that with a little thought, we'll use a different tool than originally expected. If you expect to just dive in and sort it out in your source code, then you've already a priori restricted your choice of tool, and probably also your library, algorithm, etc. (of course if you only have or know one tool then, well, 'everything looks like a nail and who needs a blueprint?'). Without planning, you'll get what grows out of the first thing that comes to mind, not the best thing you could build. The mere fact that it manages to run or stand is not a defense of the bad process. Planning is where the real thinking takes place. Sure, if all you want to do is exercise your programming skills and avoid thinking, then don't plan. But don't pretend that no one else should think or plan, or complain when someone else presents a plan to which you are expected to build (and don't be surprised 10 years on when you don't advance as far as you expected).