8 ms·

Preferring throwaway code over design docs

327 points by softwaredoug 2y ago

nickm12 2y ago
Design docs versus prototypes (called "throwaway code" in this post) is a false dichotomy. Both are ways of derisking projects and aligning others on the approach, but they work at different levels each can validate things the other can't. Here are some things I expect to see in design documents that are unlikely to show up in a prototype code review. What is the high-level description of the problem to be solved? What are the success criteria? What are the functional and non-functional requirements? What are the edge cases and failure modes and how should the system handle them? Are there multiple possible approaches and trade-offs between them? How will this code be tested and released? Prototypes, in contrast, are great for measuring performance of alternate approaches, validating unproven APIs and frameworks, and gaining practical experience with different interface design decisions. See also Leslie Lamport's article, Who builds a house without drawing blueprints? https://cacm.acm.org/opinion/who-builds-a-house-without-drawing-blueprints/ https://cacm.acm.org/opinion/who-builds-a-house-without-draw...
dboreham 2y ago
I've been doing this for more than 30 years. Never seen one design doc. At least not one that was actually used to guide the subsequent implementation.
- koolba 2y ago
  They both have their place. Ideally the design doc flows out from the proof of concept to document the non-trivial assumptions and decisions. But nothing beats an actual PoC to demonstrate that something will actually work. I like the phrase “weaponize” to refer to the evolution of a PoC into a workable application.
- BurningFrog 2y ago
  A few more years, and same here. Design discussions can be very useful though.
jprosevear 2y ago
One of the challenges with this approach is answering "how much will it cost" and "how long will it take" - that being said, its often hard for non-developers to articulate exactly what they want without connecting it to something more concrete in the form of user interface.
- boxed 2y ago
  Those questions aren't answerable in the first place. I like the general idea behind ShapeUp: don't ask "how long will it take" but "how much time are you willing to literally throw in the bin to learn more about the problem". Committing to research is easy and HONEST. Committing to a finished product by a date is incredibly hard/impossible and a lie. The first duty of all humans must be to truth.
  - SpicyLemonZest 2y ago
    It's quite rare to be in a scenario where not making timeline estimates is even an option. * If you're B2B, your marginal clients are constantly deciding whether to sign or renew their contracts, and their money directly depends on promises you make them about when features they want will be available. * If you have competitors, you have to evaluate how your product will match up with them over time. If there's some killer feature you could build with 3 engineers in the next quarter, you should probably do it. If there's a killer feature your competitors could build that fast, but you have some tech debt that would make it take 3 years, you'd better find a strategy to make that feature less important. * If you have a large or growing product, you have more potential projects to do than people to do them, so you're going to have to decide which will produce the most benefits for a given unit of time investment. If you have a small, non-contract-based project with no direct competitors? Sure, it's possible to get away with the "we'll finish when we finish" strategy. But there's not a ton of space in that niche, and unless you get quite lucky it's not where the big bucks are going to be.
    - boxed 2y ago
      I think this is largely a matter of habit, and not of reality. Yes, you might get the business short term if you lie and say some feature will be available Q3. But over time that type of constant lying erodes trust and hurts you. I get it, you might need to do it to survive in the beginning because competitors will be doing the lying. But I'm saying you need to stop lying as soon as possible for the long term health of the relationship.
miscaccount 2y ago
A design doc would help narrow down the number of prototypes to 2 to 3 in all the available options. This is especially useful if you are exploring adding something completely new. Though i feel that showing is better than telling, when new people onboard they have a easier time understanding via a design doc than code.
stasiu 2y ago
Does anyone have a design doc format that they prefer for backend development? We’ve been working with ADRs, is that similar or the same as a design doc? PS. I like the approach. Sounds like something I read before where devs would throw away their code everyday until they were satisfied with the result.
aleksiy123 2y ago
I don't think they are mutually exclusive? Design doc is broader. It's goal is communication. Sometimes you need to communicate other than in code. Diagrams, images, words etc...
- corytheboyd 2y ago
  Agree. It’s very hard for anyone who isn’t the author, or otherwise intimately familiar with the code, to understand changes at a glance. The reader needs high level explanations and documentation to quickly build the correct mental model to understand the change in context. If you can look at 1000 lines of diff and accurately tell what it’s doing, and much more importantly, the upstream and downstream implications… you’re either lying, or somehow work in a perfect hermetic vacuum of verifiability that I am very jealous of.
hcs 2y ago
As they say, > Build one to throw away (You will anyway) (Probably first phrased "plan" by Fred Brooks)
- JKCalhoun 2y ago
  It's always been the way I've coded, for better or worse. I code fast prototypes though — throwing them out is easy. And when I kick off the 2nd iteration I have new insights going in. (By the 3rd iteration I'm even hanging on to a few functions from the previous iterations.)
lubujackson 2y ago
I agree, to a point. Successful design docs require MORE work (or far more meeting time, at least) than rapid prototyping. Because they need to mentally step through all the logic, gotchas and integration issues without writing a line of code. For a math metaphor, it's like doing a complex problem in your head then making a document stating which mathematical tools you will use, THEN writing down the actual formula. Versus the "show your work" approach of trying a few things, recalibrating or re-routing, then settling on the final approach. So the design doc approach is truly terrible and inefficient. Except... If a Very Smart Person is making the design doc and can pump out a perfect plan quickly... And/or if the engineers implementing the solution are too junior to understand the build/rebuild approach... Or if they are likely to miss various integration footguns... Or if they are likely to go far down the wrong path completely... Or if the organization is of such size that no one has understanding of all the parts and integration parts so you need to set hard I/O requirements for clean handoffs. There may be more reasons for design docs, but I strongly agree they should only be used when necessary and certainly not required so that management gets to feel useful. They add a hefty tax to development speed and it's management's job to understand that cost/benefit ratio.
- fwip 2y ago
  It think it mainly depends on the difficulty of the problem. If you're working on a very difficult math problem - say, a novel proof - you're definitely going to lay out the tools and techniques, the various steps of the proof, before you sit down and start writing it out. But for homework problem #7 of 14, just start doing it - you'll figure it out. Similarly, if you're writing a CRUD app in a stack you've used before, you can probably just start. But if you're writing something complicated that you haven't done before, you should probably visit the whiteboard before the IDE.
revskill 2y ago
Lol at work i often merge prs with huge number if file changes as a result of treating it as a poc or draft first.
ElatedOwl 2y ago
Writing is really beneficial for exploring the problem space. Many times I’ve confidently thought I understood a problem, started writing about it, and come away with new critical questions. These things are typically more visible from the abstract, or might not become apparent in the first few release milestones of work. I’m reminded of a mentor in my career, who had designed an active/active setup retroactively for a payment gateway. He pulls up a Lucidchart and says “this diagram represents 6 months of my life”. They’re not always necessary or helpful. But when they are you can save weeks of coding with a few days of planning.
- softwaredoug 2y ago
  I agree writing is beneficial. But I also find this works with coding. And they go hand in hand for exploring in my experience. And in the end a good PR has a lot of writing too and has this effect. IMO this sort of well documented draft PR serves as a better design proposal because pure writing causes you to forget important constraints you only remember when you’re in the code.
  - __MatrixMan__ 2y ago
    Agreed. You can write prose or implementations or tests beforehand and I don't think it matters too much which you choose, just as long as you give yourself a phase 2 for incorporating the learning you did in phase 1 and put a reality check of some kind in between them. The only problem with having the draft being implementation is that maybe you'll get pressured into shipping the draft.
    - withinboredom 2y ago
      I’ve had to ship the draft a few times in my career. Usually when the actual code would have been weeks or months more of work (draft has poor architecture, while a proper architecture would have been just as much work as the draft). Twice it was due to showing a demo and a decision maker in the audience said “we can sell this tomorrow” or something to the same effect for that org. In one case, we ran a simple a/b test as a proof of concept on whether to pursue the idea further and it added an extra million bucks a year in revenue. Nobody wanted to wait for a proper implementation. All that code is still in production, slow as shit and nobody wants to fix something that isn’t broken. If you have a draft, keep it to yourself. Use it as a personal reference when writing the design, or share snippets. Other engineers will realize you have a draft, business people won’t.
simonw 2y ago
I really like this process: using an ongoing comment thread to document design decisions along the way, as opposed to trying to formalize them in a single document. I use GitHub issues for this myself but that's functionally equivalent to using a PR - a PR is effectively a GitHub issue with an attached branch of code. I wrote more about my process here: https://simonwillison.net/2022/Jan/12/how-i-build-a-feature/#everything-starts-with-an-issue https://simonwillison.net/2022/Jan/12/how-i-build-a-feature/...
- kmoser 2y ago
  But then how do you communicate the latest consensus on all issues, e.g. for a newcomer who doesn't want to slog through months of communication, or a team member who has been part of the thread all along but can't easily find where the team agreed on a particular thing? In other words, how do you summarize the thread into final documentation?
  - softwaredoug 2y ago
    Well unfortunately there’s never “final” design documentation. Design docs go out of date pretty fast. I think it’s healthy to treat design docs like a historical artifact - true at one point in time. It’s less likely they stay up to date to reflect reality.
  - simonw 2y ago
    The documentation that needs to be kept 100% up-to-date is the usage documentation. Here's how to use this Python class library. Here's how to use this REST API. Here's how to use this CLI tool. THAT should live in the same repository as the code itself, and updates to it should be enforced as part of code review. Design documentation that describes the process that got to that point should live separately from the repo in something like GitHub Issues, because it's not guaranteed to be up-to-date but can still be referenced during code archaeology sessions when trying to figure out WHY the software is the way it is. Commit messages work too, but I prefer to have a short commit that links to an issue thread where I can find out more. I wrote about this here: https://simonwillison.net/2022/Oct/29/the-perfect-commit/#documentation https://simonwillison.net/2022/Oct/29/the-perfect-commit/#do...
hcarvalhoalves 2y ago
Another opinion piece, but no data, not even a concrete example. I get it, every software engineer has strong opinions, but that’s a weak one. If you think writing a lot of code to see what sticks is the job description, you’ll be replaced by GPT in no time - it can do it faster and cheaper. The challenge is always in getting alignment on what should be built, you won’t code your way out of that.
- softwaredoug 2y ago
  That’s exactly my point, I think you get better alignment with “show don’t tell”. Rectangles and dotted lines only get you so far. Being removed from actual code makes you forget the real constraints - the stuff that actually slows you down doesnt appear in google docs. “Here’s what I’m thinking (points at Draft PR)” gets you farther in my experiencre. And yes it’s 100% an opinion. It’s a personal blog not a peer reviewed article :) I’m happy to be wrong.
  - Arainach 2y ago
    Design docs are much easier to be reviewed. Throwaway code/a prototype is a huge amount of content where it's easy to miss things. When I go back to understand a component, I want to know why the decisions were made. A well written doc illustrates exactly that - here are the options considered, here is why we chose this option to be implemented. It can be quickly read and searched. Throwaway code - even a pull request with comments - is not the same. It takes much longer to process, much longer to review, and it's easy to miss seemingly obvious things because the important bits are surrounded by a bunch of unimportant boilerplate. Put another way: anything that could be represented by a single PR is generally not significant enough to need a design document. Anything significant enough to need a design document should be a chain of smaller PRs / commits which allow the pieces to be reviewed thoroughly by themselves and have tests to show that they each work.
  - hcarvalhoalves 2y ago
    I guess this varies largely with project, stakeholder, etc. The kinds of projects I have been involved, showing a PR would’ve been either useless to communicate anything, or have to explain why it’s “throw away” and why we can’t ship the prototype. That’s why I stressed it’s an opinion piece but no data. Unfortunately in this industry we have a lot of experience reports, but lack actual data on what is or isn’t more effective way to work.
mrkeen 2y ago
As Lamport says: the algorithm is not the code. Not all products need an "algorithm" per se, but if your product needs to do collaborative editing or something else CAP-adjacent, that algorithm is going to need to live somewhere (not in throwaway code). The right algorithm (or even if such an algorithm is possible) won't be discovered via iterating on the code base.
bluGill 2y ago
Design documentation should be done on a whiteboard. You have limited space but that forces you to write down what is important and who it doing what. in a few weens it is so different from reality that you don't feel bad about erasing it for whatever is next.
- simonw 2y ago
  ... as long as you then take a photo of that whiteboard, attach a timestamp and put it somewhere people can find it in the future. Otherwise it's not documentation at all, it's lost to the wind.
  - bluGill 2y ago
    Chatis the point - it should be lost to the wind. I have never seen design documentation worth reading except in textbooks where it is only used to explain pattens to students.
    - simonw 2y ago
      Right, and my point is that this stuff genuinely matters and is worth recording - but needs to be recorded with a very clear timestamp (hence my preference for comments in a GitHub issue or PR). Otherwise you'll inevitably find yourself re-litigating old decisions because you never recorded WHY you chose one approach over another.
      - bluGill 2y ago
        Why is important but that is a very different thing from the desing documents I used to have to write, those would not tell you why.
theptip 2y ago
Aka “Ready, fire, aim” from the Pragmatic Programmer. This approach is fine but make sure your iterative prototyping is refining some sort of e2e / acceptance test, with good comments / README describing the intent. It’s really easy for the prototype to end up being shipped and painful refactoring happening once you’re successful. For me, a lot of the time this ends up being a question of what is known vs unknown. If you have a clear customer requirement but technical uncertainty then iterating on prototypes is usually better. If you have unclear customer requirement then shipping MVPs iteratively is usually better. If you have organizational uncertainty (eg you need to compose components from multiple teams and align roadmaps, as is common in big companies) then the design doc is often the place to start.
- softwaredoug 2y ago
  I totally agree. The prototype being shipped is the #1 risk. And why even though I prefer this approach, it may be impractical if organizations can’t be disciplined.
  - kmoser 2y ago
    If you have time to rewrite the prototype twice, you also have time to write and maintain the documentation which would have made it unnecessary to rewrite the prototype twice. Not saying iterating the code is always bad, but it shouldn't be a substitute for sufficient up-front planning that would have saved programmer time. And yes, the prototype usually ships. There is often not enough time to completely rewrite it, let alone fix all the bugs and add all the necessary features.
deleted 2y ago
[deleted]
wavemode 2y ago
The design document is for documenting what problems you're trying to solve, and (critically) what problems you're not trying to solve. And the relative advantages and disadvantages of competing approaches. The mistake people make with design documents is going into too much detail on -how- you're going to solve the problem. That's where prototypes ("throwaway code") come in. The design document should just be a high-level overview.
RexySaxMan 2y ago
Being open to throwaway code before a design doc+review is an idea I promoted and tried to demonstrate in my projects at my most recent employer, but I found that it just didn't work within our engineering culture an expectations. Funnily enough, it had the most success when working on larger projects that spanned multiple teams and services, where often my team was consuming or providing an interface, and the code sample provided a clear usage pattern that other teams could critique or grok. I got the most dysfunctional comments within my own team on smaller projects and PRs (e.g. "not sure why you want to do it this way" on small code blocks, critiquing data structures used), so I'm still not sure if it was a company culture issue or team issue.
liontwist 2y ago
Which is cheaper? A change in code? Or a change on paper?
- teamonkey 2y ago
  A change on paper which needs to go though various approval stages, tasked up and finally implemented can be much more expensive than a change in code. Or the opposite.
  - liontwist 2y ago
    I absolutely agree. And the other comments here have pointed out the danger of code is that someone will want to ship your draft. So business processes can kill either one.
allenu 2y ago
I'm a big fan of prototyping to explore a problem space. I think some initial design sketches are useful, but you often reach a point where you can only learn by implementing. I've encountered so many design constraints in the past that I couldn't have planned for, but perhaps others are better at comprehensively thinking through a problem space than I can. I agree with the blog post that doing a hacky solution is very helpful to understand the problem space better, although I think it's something that's challenging in an organization. In a lot of orgs, it might be viewed as a waste of time to work on something hacky. It could also come across as wasting people's time by engaging in too many discussions over PRs. People want shipping solutions today, not explorations that might need to be rewritten later. Asking for feedback might also come across as someone being unsure of a solution and needing "help" on it. The dynamics of working in a team generally nudge devs to make more conservative moves and writing more up-front design docs, which will be slower and safer. I'm not arguing that's a bad thing, though. You need the documentation to communicate intent across an org and many other people will need to pick up the work, too. A PR may not provide enough space to comprehensively explain the overall design. As an indie dev now, I find sketching some designs, followed by prototyping, then "massaging" the prototype into a working, shippable solution the ideal workflow. However, it only works because I'm solo and don't need to worry about getting an okay on potentially risky solutions or having to communicate and get buy-in on implementations. In a company that has lots of other devs and lots of paying customers, I wouldn't be able to do things that way, and for good reason.
- damethos 2y ago
  > In a company that has lots of other devs and lots of paying customers, I wouldn't be able to do things that way, and for good reason. Why not? You do the "sketching/mockup" of most of the flow (without going into too much design detail) in order for the team to understand better what you are going to build. Then, everybody can provide feedback based on their perspective, do a couple of iterations, then prototype (which if done well will be the initial version of the shippable solution) and then iterate again.
jnsaff2 2y ago
"Plans are worthless, but planning is essential".
CharlieDigital 2y ago
No. Just no. Design docs should capture reasons. Even if the code is throwaway, the reasons for the flow and process modelling for the use case don't change at the core. Some implementation details might change and the design may certainly also change accordingly, but the process is generally stable. That's what should be captured in design docs.
jasonpeacock 2y ago
This is called prototyping, which is a valuable part of the design process; some people call it "pathfinding". These are all inputs into the design. But a design is still needed, of the appropriate size, otherwise you're just making things up as you go. You need to define the problem your are solving and what that solution is. Sometimes that's a 1-page doc without a formal review, sometimes it's many more pages with weeks of reviews and iterations with feedback. Don't forget: "weeks of coding can save hours of planning" ;)
- sevensor 2y ago
  Agreed, why not both? In fact, I’d say, first write up a theory, then demonstrate that it does or does not work using a prototype, then write the actual design doc. At all times, and continuing into the implementation phase, prioritize the disposability of your code. The easier it is to delete, the better.
  - softwaredoug 2y ago
    I think my argument would be that they could be the same artifact. Hence my usage of Draft PRs with a lot of rich documentation. And a willingness to throw it all away if you don't think its ultimately the right approach. The real problem is the industry's inability to throwaway first solutions, so we introduce this (IMO inefficient) 'design doc' step as a safety mechanism
    - makeitdouble 2y ago
      I enjoyed the writeup and think it's a nice idea depending on the situation, but with serious limitations (for context, I also do prototype first, but still right a design doc at some point) The main issue to me is exactly that we do throw away the prototype implementation. Writing rich documentation for throwaway code is tedious, and at the early stages I see a split between the people that mostly read the doc and only glance over the code, those who almost ignore the docs and focus on the code, and some rare people actually looking at both and getting confused at the discrepancies ("you say you in your doc you store values in the remote database, but this code only writes to the local one, which one will stay ?") Perhaps I'm just not good at docs, but doing code heavy prototypes with only very light and high level doc was way more efficient. Then when we settle on one direction, I can freeze the main points in a separate documentation and rewrite the prototype in a more serious version. Having a separate design docs also helps when the system components are split across many area. Having the doc even when it's a compact proposition standardizes the process and you never have to ask upfront if it will be needed or not.
sesm 2y ago
Prototypes discover constraints, docs document them (as well as what problem is being solved, what solution was chosen under those constraints and what are consequences).
starkparker 2y ago
> Another important point is on using PRs for documentation. They are one of the best forms of documentation for devs. This feels true, and also why design docs are important for projects that involve roles beyond software development, where PRs can be among the worst forms of documentation.
patrulek 2y ago
Design docs are only as good as your knowledge about the problem you want to solve and knowledge about tools available for solving it. If there are more unknowns than knowns imo its better to start with prototype to explore problem first and then eventually come back to planing.
djmips 2y ago
I wonder about all of the best inventions of all time and how many came from prototyping and how many were the result of a real peachy design doc.
rsanek 2y ago
almost every single time I've seen 'prototyping' done that was originally intended to be throwaway, it was ultimately the basis of the actual implementation.
rsanek 2y ago
the idea that you can get value from just creating draft PRs without integrating them at all does not match my experience.
ChrisMarshallNY 2y ago
The biggest issue that I’ve had with design docs, is that nobody reads them; even if required by their employer. The biggest issue that I’ve had with prototyping, is that people consider it “ship” code, and force me to use it as final code. I find that I’m best served with a hybrid approach, where I spend a lot of time planning and documenting, but basically, for myself, then writing ship-Quality prototype code, so that using it in the end product is OK.
- kccqzy 2y ago
  The reason people don't like to read the average design doc is because the average software engineer doesn't have enough writing skills to express the concept clearly and concisely without editing. The design doc becomes a mumble jumble of raw notes that nobody really understands except the author. And then people dread reading this kind of raw notes. However, if someone tells that design doc writer that this is something like a term paper at school that is being graded, they can actually improve their writing by quite a bit by doing some editing. So the symptom is really the same as prototyping: people write draft-quality design docs and magically hope it to be a good quality piece of writing suitable for a wider audience. What they need is a few rounds of editing, just like when they write prototype code they need a few rounds of refactoring.
  - mianos 2y ago
    As much as I get frustrated with GPT4's limitations when it comes to code, it's quite good at expanding detailed bullet points into solid design prose. You still have to read it back and triple check it, as you would your own work, but you don't need all the time it takes to extensively expand it from draft. Also, which it is in context it's quite good at documenting what needs to be done to test it.
    - ChrisMarshallNY 2y ago
      I agree. I have used it for just that.
    - pclmulqdq 2y ago
krisoft 2y ago
I like the idea and we use it at work often. One pitfall one has to be aware is that it is easy for the people who are asked to provide feedback on the prototype to get bogged down in the details. What you want is people to squint and tell you if they like the general approach, but what often happens is they tell you that you need more unit tests and you could use a ternary operator here and here. (The particular details will of course differ in each case.) The reason for that, in my opinion, is that your thing looks like a PR and therefore people default to the kind of review they do for PRs. But since this is a different beast it needs a different mindset during review. And of course the only possible solution for that is proactice and active communication to get everyone on the same page.
jp57 2y ago
We imagine software efforts that go through a clean, neat flow: We write a design doc. Then make small incremental changes in a PR to rollout the functionality. Our git histories look clean and orderly. Like a steady march of progress. Who imagines this? Professors who teach software engineering classes? This reminds me of people who think that you write prose (essays, stories, novels, etc) by writing an outline and then "filling it out" with prose, as if in the process you will never discover anything that requires you to rewrite or restructure the document. Nobody writes that way. First drafts are always terrible and basically all good writing has been heavily revised. Writing code is much more like writing than it is like building a house or a bridge.
- throwaway2037 2y ago
  For myself, I always find great value in debugging new code that I have written. Something about stepping line by line through new logic, and viewing variables/memory really helps me to improve my code. "Oh, I don't need that local var." "Oh, I should add a temp var to make the code easier to debug here." "Oh, this code is weird when the collection that we iterate is empty." No matter how old I get, and no matter how much code I write, I always discover new things when I debug my newly written code. I guess this could be compared to an author writing a first draft, then going back to read it... or reading it aloud to themself or another person.
robertclaus 2y ago
In my experience there is a MASSIVE difference in the type of feedback someone gives on code vs a design. A design doc encourages "why" questions to get everyone thinking about the problem space. For example, a design doc comment might be "why are we suggesting a Rust Webserver when nobody in the company is proficient in Rust yet?". In my experience those more subtle questions are much harder to raise once a prototype is working - "why does the team's experience matter? look how great it works! If you don't block it we could get this to production in a week by just polishing the prototype!"
- bawolff 2y ago
  This is not neccesarily a bad thing though. Lots of "why" questions are really counterproductive bikeshedding. Especially when it comes from just reviewing a design as opposed to working code.
designAndCode 2y ago
Preferring throwaway code over design docs (softwaredoug.com) is a Horrible take on software development.
baazaa 2y ago
A lot of my code takes in garbage data and does some complicated stuff to produce useful outputs. Almost all the difficulty comes from hidden problems in the data upstream, including very often the data contradicting itself (a lot of fuzzy matching, 'voting' to determine the truth, etc.) None of these problems are ever-known beforehand, and can typically only be discovered after a lot of work has been done to make the data more intelligible (i.e. in the process of writing of my code). I've realised over time that everyone else who prefers the design-doc approach refuse to do work like this. There's just a whole class of problems that are too hard without prototyping.
- softwaredoug 2y ago
  Right I feel like the problem isn't "prototyping is bad". Prototyping is good! But sadly many companies and devs aren't disciplined enough to throw away first solutions. And that's the real problem. And its not just the companies, developers get too attached to their first solution, rather than using it as a way to discover knowledge. Companies need to reward knowledge discovery, not just "shipping to prod"
rich_sasha 2y ago
I think the key is to have a solid understanding that this is throwaway code. I know of, erm, one quite company, fairly well known in its big industry, where indeed no one gathers any requirements and a junior guy is told to type it all in - with the view that it's probably 90% correct and the rest can be ironed out at some stage, or at worst rewritten. But what tends to happen is thus: 1. The first draft tends to address all the wrong problems, doesn't abstract the right things, is over and under engineered in all the wrong places. Fine, it's a draft I guess 2. But here's the kicker: unless it's really unusable, there is now pressure on users to accept the draft, because changing it, perhaps substantially, requires work, and as it it sort of kind of works, if you squint. And this thing is there and you can pretend it's a job done. I think ploughing in to writing code works if you ha r a decent idea of what you need to achieve and what the pinch points are. Without that it can be quite an expensive and frustrating approach.
gigel82 2y ago
If doing greenfield work, planning sounds nice, but if you're integrating with crusty / legacy systems that are poorly documented (if at all) planning is a waste of time; you'll end up saying "Library X will do Y" a lot only to find out none of that works the way you thought. So for brownfield, I may have a plan (written down or not) but it's mostly code (some throwaway) just to uncover how things actually work.
jwcacces 2y ago
But with without design docs, how will my hordes of low cost contractors know what to do?
nhumrich 2y ago
Design docs are incomplete without reference implementation code. Which would require you to actually follow this process.
w10-1 2y ago
Opinions sans reputation or data can still be helpful when they identify the landscape and issues, e.g.,: A main goal of design is to identify what's not feasible through logic. So much easier than prototyping. But still "can it be done?" is a far cry from "can we do it?". The benefit of prototyping is to show that something is possible. There the key question is integration: can persons Pn make code C on system S that meets both goal X and constraint Y - i.e., a design as product development. Leaving aside bad-faith behaviors, the real question is socialization: 1. how to gather collective wisdom in some relatively natural and encouraging manner to encourage collective deep consideration of hard problems to avoid waste and get things done. And 2. the same for motivation: getting everyone aligned, understanding their role and the quality/schedule risks. Given the uncertainties and costs of product development, the prototype has significant advantage of seeming "real" relative to some "ideal" solution, and thus can bias teams to the concrete, particularly when issues are contended. Prototype-driven planning likely reflects lack of organizational cohesion (and ironically kicks that can further down the road). So generally I see prototyping as validating designs, and try to make the design discussions lean enough to engage otherwise-prototyping engineers.
llm_trw 2y ago
What I've found is that there is no such thing as throwaway code if you share it with anyone. I've had code I threw together in 10 minutes end up in production after putting it in a 'temporary' repo.
- bdndndndbve 2y ago
  For a greenfield project that's fine - solve the issues that come up as they come. Someone is getting value right away. Code you throw away makes the most sense to me for prototyping cross-cutting features in existing systems. A lot of companies can accumulate a ton of crud in only a few years of development time, and it follows Conway's Law that the crud is shaped like the org tree. Writing a throwaway feature end-to-end helps to identify the interfaces between the teams and subsequently components of the software. This is also why I'm a big fan of assembling project teams over having teams "own" an area. Everyone on the project team is responsible for the project working well. Otherwise every team is worried about their small domain.
  - llm_trw 2y ago
    This is how green field projects become brown field projects in 4 weeks.
bdd8f1df777b 2y ago
Design docs are critical to your promotion. The boss and the committee do read your design docs, sometimes very carefully. Only your peers and at most your TL read your code.
- klabb3 2y ago
  > the committee do read your design docs, sometimes very carefully Yadda yadda, that may be true sometimes but that the quality of the doc would get you promoted makes no sense and is also not a good metric. I think most of these committees look at who approved it and what known people thought/wrote in response. I was told in this promo-game to try to get comments from high-level people for this reason. That is more a popularity contest, and less a competition of well articulated ideas. I think most people here want to improve the way things are. We talk about engineering practice to improve the practice, not to please management or give career advice. Usually, at least. This is where it happens first. A bunch of engineers (or just generally people with boots on the ground) get together and find better ways to do things. Before agile was mainstream and corrupted beyond recognition, the waterfall model was the way recognized by management and working within that model would have gotten you promoted easier. Things evolve.
m1n1 2y ago
We had to build and launch something by a deadline in order to avoid renewing a contract that would have cost $x mil. But we discovered we weren't going to finish in time with the resources and the approach that was planned. So I got approval to hack out a temporary impartial suboptimal version and we were able to take off in time. This has allowed us to fly for a bit while others finish building out the permanent proper version of that part of the wing. In fact, during our flight we discovered missed requirements in the original design. This has delayed that proper version's release to prod. But I've been able to add that quickly to my hack and keep us flying. My hack doubles as a production support tool. And as an alternate route if the permanent version needs to be paused because of a bug. Yes it's a partial imperfect hack but it has benefits. Someone has complained about the language I used since it is less common. But remember, we weren't going to be able to take flight with the existing resources and approach. We would have needed more and/or faster developers in the favored language to meet the deadline. If any present employee (including me) had bandwidth and was able to be as productive in the favored language as I was building my hack in the uncommon language, that employee would have been tasked to build the permanent solution on time. That option was not available. Anyways, if you have an existing production support tool, it's also a place where prototype features can live for a while.
- Aditya_Garg 2y ago
  What was the language?
  - m1n1 2y ago
    I think it's not uncommon for a dev to be faster with one language than another. And for another dev to know the same two languages but be more productive in the opposite direction. (And I am mindful that the bar was much lower for me -- being a temporary hack, my stuff didn't have to integrate fully or have the same level of production manners) But here are two factors that make me faster in the uncommon language. You know the usual debugger experience where if you keep stepping or you set a breakpoint and then later realize the interesting part is actually behind you? Which means you have to start your scenario again? Well, the uncommon language has a recording debugger so you can visit any points in front of or behind you, and see what any variable or return value was. You're not limited by the current stack because the recorder captured every package you told it to from the beginning Even a third party package... This means I only have to debug once to find the bug, not n times. And the language is expressive and pliable enough that this debugger was implemented in the language itself... And mostly by one guy -- not me of course -- it didn't take a whole company to implement it. And you know how in some languages like Java if your car (program) starts acting up in LA, you have to update the blueprint, send it to the car factory, build the new car, drive it back to LA, and try the same left turn to see it it still ferks? With the uncommon language, I can stay in LA and change the car while the engine is still running, n times before the 2nd Java car arrives. The language is Clojure.
agentultra 2y ago
I'm kind of on the fence about this approach. In the worst case you end up wasting time on a lot of dead ends. It's in such a situation that I kick myself for not spending time thinking about the problem before starting to write code. The best times I've had with writing design documentation has been when I thought about the problem enough that I could specify the properties necessary for a correct implementation. Depending on the scope of the problem I might use property tests or model checking. In any case, thinking about the problem up-front tends to prune away dead-ends before you head down them. (Of course, you can't do much about a bad specification except try to avoid them... learning how to write good ones takes experience, wisdom, and constructive input from knowledgeable colleagues). Update: I’m on the fence because I’ve also had a lot of success with implementing partial solutions: just get something good enough that works for some use cases and improve as you go.
Nezghul 2y ago
I wish my employers would value throwaway code or design docs.
charlie0 2y ago
This makes me shudder because I've never seen this done in practice. What always happens is the code builds up like Jenga until no one wants to touch it.
- hasbot 2y ago
  And it's so obviously bad that new hires want to re-implement from scratch even though they don't have complete knowledge of what the software does.
hulitu 2y ago
> Preferring throwaway code over design docs Why writing it if you trow it away anyway ?
ozim 2y ago
I don’t have link handy but one of the good talks that is posted on YT is about explaining how writing code is the „design phase” and not what a lot of people think „build phase”. Build phase happens at the compile time and at runtime.
nertirs1 2y ago
I have been moving towards integration tests as documentation approach, because in a fast moving environment anything that is not constantly verified has a tendency to become false.
- hitchstory 2y ago
  How do you do that? Im curious because I wrote a framework for this (same name as my username) but when I talk about the idea I receive a sea of blank faces.
bfung 2y ago
Except, how long does it take to throw the code away? Sometimes never. Write short designs; Goals, constraints, options. Prevents the tech debt from building over time and signals better when to throw chunks of systems away.
marcyb5st 2y ago
I don't agree. I believe that when the solutions' space is big design docs work best. If they are done correctly they are a (shallow) breadth-first search in the space. Specifically if in your design doc include "alternatives considered". Additionally, having multiple people looking at your doc you can prune some possible paths. A breadth-first search is useful when you don't know much about the intricacies of the problem/topic at hand, and so you need some ground work to take informed decisions. If, instead, the solution space is narrow then by all means do a prototype/throwaway PR/... to validate the approach.
gareve 2y ago
I think it all depends on the size of the team. Very small team and too many design docs, not good. Huge team, multiple timezones, multiple squads, and few design docs, not good either. And then you balance with all the values in between depending on your team size & culture. Even within the same company, your approach will/should change as it grows. There's a critical point where move fast and break things approach will eventually end up with too many outages, production bugs, unpolished/confusing product, and last but not least, FTC eye watering fines.
LAC-Tech 2y ago
I find myself researching and thinking a lot more about things before I actually program these days. It takes longer before I write, but my code is shorter and more to the point. I don't think I'm personally capable of explorative coding. I get too lost in the weeds and lose sight of the problem.
deleted 2y ago
[deleted]
throw4321 2y ago
Does your task need great code? Not a rhetorical question. Often the goal is the functional minimum. If that's your gig, it's hard to appreciate code quality maximization, and vice versa. If you do maximize quality, I'll one-up the suggestion in the article. Treat your first write as throwaway code. And your second. Up until the point where the rewrite would be roughly identical. It's basically early refactoring, but with the code at its freshest in your mind. Coding it the first couple times implicitly maps out the problem domain. You also leave no internal technical debt on the table. A surprising amount reveals itself right after you wrote it in. It gnaws at your ability to proceed. Subconsciously, it splits your attention in two: how the code is and how it should be. With each "fail" your attention spreads out and thins out. Finally, this habit makes you more fluid in the language. Quality-maximized code takes longer, but your actual typing rate ends up being much faster.
nerder92 2y ago
So we are basically re-discovering XP practices? (http://www.extremeprogramming.org/rules/spike.html http://www.extremeprogramming.org/rules/spike.html)
beart 2y ago
When a stakeholder comes back 6 months after project launch complaining about missing/incorrect features, I can't use throwaway code to prove the project was built to spec.
iamalexm 2y ago
Design docs are great for high-level orientation. If you are laying out all your code structure around it, you are doing it wrong. It's great to use the for what patterns will be used (using a facade pattern for example). It gives eng's a guide to how to implement at a high level and it should identify points of non-functional requirements; speed requirements, monitoring, security, etc. Throwaway code doesn't even touch on that. It should also put in scope some of the architecturally significant decisions that need to be made. While throwaway/prototype code can address some of that, it doesn't always identify it and talk about _why_ it is important. In short, doing both is the best thing you can do and you should scope your design docs correctly.
dozzman 2y ago
The critical objective either of these approaches is aimed at achieving is helping you _think deeply_ about the problem; how that is best done largely depends on the software engineer. I feel design docs are a way to ensure that you indeed think through a problem as much as they are a tool for peer review. If you wen't through a fairly standard educational system, it's not unfamiliar to use writing as a way of thinking more deeply about a problem and communicating those thoughts with others (namely your teacher) -- a design doc is no different. This can fail when design docs are written as templated box-ticking exercises and address more superficial technical questions than the core problem of course; it actually needs to address the problem and that is very contextual in my experience. However some folks are just better at solving problems with a more hands-on approach, in which case throwaway code may be more effective. If that is you then go for it, though its likely you'd need to still need to write _something_ to either document changes or communicate your decisions/trade-offs with the rest of your team. Fundamentally just do what allows you to solve problems best and take into consideration how to best work with your team. There is no one-size-fits-all solution to _thinking_ and broadly no-one cares how you work (I believe, I mean I certainly don't) if you're efficient, communicate well and get the job done to a high standard.

327 points by softwaredoug 2y ago

Design docs versus prototypes (called "throwaway code" in this post) is a false dichotomy. Both are ways of derisking projects and aligning others on the approach, but they work at different levels each can validate things the other can't. Here are some things I expect to see in design documents that are unlikely to show up in a prototype code review. What is the high-level description of the problem to be solved? What are the success criteria? What are the functional and non-functional requirements? What are the edge cases and failure modes and how should the system handle them? Are there multiple possible approaches and trade-offs between them? How will this code be tested and released? Prototypes, in contrast, are great for measuring performance of alternate approaches, validating unproven APIs and frameworks, and gaining practical experience with different interface design decisions. See also Leslie Lamport's article, Who builds a house without drawing blueprints? https://cacm.acm.org/opinion/who-builds-a-house-without-drawing-blueprints/ https://cacm.acm.org/opinion/who-builds-a-house-without-draw...

dboreham 2y ago

I've been doing this for more than 30 years. Never seen one design doc. At least not one that was actually used to guide the subsequent implementation.

koolba 2y ago
They both have their place. Ideally the design doc flows out from the proof of concept to document the non-trivial assumptions and decisions. But nothing beats an actual PoC to demonstrate that something will actually work. I like the phrase “weaponize” to refer to the evolution of a PoC into a workable application.
BurningFrog 2y ago
A few more years, and same here. Design discussions can be very useful though.

jprosevear 2y ago

One of the challenges with this approach is answering "how much will it cost" and "how long will it take" - that being said, its often hard for non-developers to articulate exactly what they want without connecting it to something more concrete in the form of user interface.

boxed 2y ago
Those questions aren't answerable in the first place. I like the general idea behind ShapeUp: don't ask "how long will it take" but "how much time are you willing to literally throw in the bin to learn more about the problem". Committing to research is easy and HONEST. Committing to a finished product by a date is incredibly hard/impossible and a lie. The first duty of all humans must be to truth.
- SpicyLemonZest 2y ago
  It's quite rare to be in a scenario where not making timeline estimates is even an option. * If you're B2B, your marginal clients are constantly deciding whether to sign or renew their contracts, and their money directly depends on promises you make them about when features they want will be available. * If you have competitors, you have to evaluate how your product will match up with them over time. If there's some killer feature you could build with 3 engineers in the next quarter, you should probably do it. If there's a killer feature your competitors could build that fast, but you have some tech debt that would make it take 3 years, you'd better find a strategy to make that feature less important. * If you have a large or growing product, you have more potential projects to do than people to do them, so you're going to have to decide which will produce the most benefits for a given unit of time investment. If you have a small, non-contract-based project with no direct competitors? Sure, it's possible to get away with the "we'll finish when we finish" strategy. But there's not a ton of space in that niche, and unless you get quite lucky it's not where the big bucks are going to be.
  - boxed 2y ago
    I think this is largely a matter of habit, and not of reality. Yes, you might get the business short term if you lie and say some feature will be available Q3. But over time that type of constant lying erodes trust and hurts you. I get it, you might need to do it to survive in the beginning because competitors will be doing the lying. But I'm saying you need to stop lying as soon as possible for the long term health of the relationship.

miscaccount 2y ago

A design doc would help narrow down the number of prototypes to 2 to 3 in all the available options. This is especially useful if you are exploring adding something completely new. Though i feel that showing is better than telling, when new people onboard they have a easier time understanding via a design doc than code.

stasiu 2y ago

Does anyone have a design doc format that they prefer for backend development? We’ve been working with ADRs, is that similar or the same as a design doc? PS. I like the approach. Sounds like something I read before where devs would throw away their code everyday until they were satisfied with the result.

aleksiy123 2y ago

I don't think they are mutually exclusive? Design doc is broader. It's goal is communication. Sometimes you need to communicate other than in code. Diagrams, images, words etc...

corytheboyd 2y ago
Agree. It’s very hard for anyone who isn’t the author, or otherwise intimately familiar with the code, to understand changes at a glance. The reader needs high level explanations and documentation to quickly build the correct mental model to understand the change in context. If you can look at 1000 lines of diff and accurately tell what it’s doing, and much more importantly, the upstream and downstream implications… you’re either lying, or somehow work in a perfect hermetic vacuum of verifiability that I am very jealous of.

hcs 2y ago

As they say, > Build one to throw away (You will anyway) (Probably first phrased "plan" by Fred Brooks)

JKCalhoun 2y ago
It's always been the way I've coded, for better or worse. I code fast prototypes though — throwing them out is easy. And when I kick off the 2nd iteration I have new insights going in. (By the 3rd iteration I'm even hanging on to a few functions from the previous iterations.)

lubujackson 2y ago

I agree, to a point. Successful design docs require MORE work (or far more meeting time, at least) than rapid prototyping. Because they need to mentally step through all the logic, gotchas and integration issues without writing a line of code. For a math metaphor, it's like doing a complex problem in your head then making a document stating which mathematical tools you will use, THEN writing down the actual formula. Versus the "show your work" approach of trying a few things, recalibrating or re-routing, then settling on the final approach. So the design doc approach is truly terrible and inefficient. Except... If a Very Smart Person is making the design doc and can pump out a perfect plan quickly... And/or if the engineers implementing the solution are too junior to understand the build/rebuild approach... Or if they are likely to miss various integration footguns... Or if they are likely to go far down the wrong path completely... Or if the organization is of such size that no one has understanding of all the parts and integration parts so you need to set hard I/O requirements for clean handoffs. There may be more reasons for design docs, but I strongly agree they should only be used when necessary and certainly not required so that management gets to feel useful. They add a hefty tax to development speed and it's management's job to understand that cost/benefit ratio.

fwip 2y ago
It think it mainly depends on the difficulty of the problem. If you're working on a very difficult math problem - say, a novel proof - you're definitely going to lay out the tools and techniques, the various steps of the proof, before you sit down and start writing it out. But for homework problem #7 of 14, just start doing it - you'll figure it out. Similarly, if you're writing a CRUD app in a stack you've used before, you can probably just start. But if you're writing something complicated that you haven't done before, you should probably visit the whiteboard before the IDE.

revskill 2y ago

Lol at work i often merge prs with huge number if file changes as a result of treating it as a poc or draft first.

ElatedOwl 2y ago

Writing is really beneficial for exploring the problem space. Many times I’ve confidently thought I understood a problem, started writing about it, and come away with new critical questions. These things are typically more visible from the abstract, or might not become apparent in the first few release milestones of work. I’m reminded of a mentor in my career, who had designed an active/active setup retroactively for a payment gateway. He pulls up a Lucidchart and says “this diagram represents 6 months of my life”. They’re not always necessary or helpful. But when they are you can save weeks of coding with a few days of planning.

softwaredoug 2y ago
I agree writing is beneficial. But I also find this works with coding. And they go hand in hand for exploring in my experience. And in the end a good PR has a lot of writing too and has this effect. IMO this sort of well documented draft PR serves as a better design proposal because pure writing causes you to forget important constraints you only remember when you’re in the code.
- __MatrixMan__ 2y ago
  Agreed. You can write prose or implementations or tests beforehand and I don't think it matters too much which you choose, just as long as you give yourself a phase 2 for incorporating the learning you did in phase 1 and put a reality check of some kind in between them. The only problem with having the draft being implementation is that maybe you'll get pressured into shipping the draft.
  - withinboredom 2y ago
    I’ve had to ship the draft a few times in my career. Usually when the actual code would have been weeks or months more of work (draft has poor architecture, while a proper architecture would have been just as much work as the draft). Twice it was due to showing a demo and a decision maker in the audience said “we can sell this tomorrow” or something to the same effect for that org. In one case, we ran a simple a/b test as a proof of concept on whether to pursue the idea further and it added an extra million bucks a year in revenue. Nobody wanted to wait for a proper implementation. All that code is still in production, slow as shit and nobody wants to fix something that isn’t broken. If you have a draft, keep it to yourself. Use it as a personal reference when writing the design, or share snippets. Other engineers will realize you have a draft, business people won’t.

simonw 2y ago

I really like this process: using an ongoing comment thread to document design decisions along the way, as opposed to trying to formalize them in a single document. I use GitHub issues for this myself but that's functionally equivalent to using a PR - a PR is effectively a GitHub issue with an attached branch of code. I wrote more about my process here: https://simonwillison.net/2022/Jan/12/how-i-build-a-feature/#everything-starts-with-an-issue https://simonwillison.net/2022/Jan/12/how-i-build-a-feature/...

kmoser 2y ago
But then how do you communicate the latest consensus on all issues, e.g. for a newcomer who doesn't want to slog through months of communication, or a team member who has been part of the thread all along but can't easily find where the team agreed on a particular thing? In other words, how do you summarize the thread into final documentation?
- softwaredoug 2y ago
  Well unfortunately there’s never “final” design documentation. Design docs go out of date pretty fast. I think it’s healthy to treat design docs like a historical artifact - true at one point in time. It’s less likely they stay up to date to reflect reality.
- simonw 2y ago
  The documentation that needs to be kept 100% up-to-date is the usage documentation. Here's how to use this Python class library. Here's how to use this REST API. Here's how to use this CLI tool. THAT should live in the same repository as the code itself, and updates to it should be enforced as part of code review. Design documentation that describes the process that got to that point should live separately from the repo in something like GitHub Issues, because it's not guaranteed to be up-to-date but can still be referenced during code archaeology sessions when trying to figure out WHY the software is the way it is. Commit messages work too, but I prefer to have a short commit that links to an issue thread where I can find out more. I wrote about this here: https://simonwillison.net/2022/Oct/29/the-perfect-commit/#documentation https://simonwillison.net/2022/Oct/29/the-perfect-commit/#do...

hcarvalhoalves 2y ago

Another opinion piece, but no data, not even a concrete example. I get it, every software engineer has strong opinions, but that’s a weak one. If you think writing a lot of code to see what sticks is the job description, you’ll be replaced by GPT in no time - it can do it faster and cheaper. The challenge is always in getting alignment on what should be built, you won’t code your way out of that.

softwaredoug 2y ago
That’s exactly my point, I think you get better alignment with “show don’t tell”. Rectangles and dotted lines only get you so far. Being removed from actual code makes you forget the real constraints - the stuff that actually slows you down doesnt appear in google docs. “Here’s what I’m thinking (points at Draft PR)” gets you farther in my experiencre. And yes it’s 100% an opinion. It’s a personal blog not a peer reviewed article :) I’m happy to be wrong.
- Arainach 2y ago
  Design docs are much easier to be reviewed. Throwaway code/a prototype is a huge amount of content where it's easy to miss things. When I go back to understand a component, I want to know why the decisions were made. A well written doc illustrates exactly that - here are the options considered, here is why we chose this option to be implemented. It can be quickly read and searched. Throwaway code - even a pull request with comments - is not the same. It takes much longer to process, much longer to review, and it's easy to miss seemingly obvious things because the important bits are surrounded by a bunch of unimportant boilerplate. Put another way: anything that could be represented by a single PR is generally not significant enough to need a design document. Anything significant enough to need a design document should be a chain of smaller PRs / commits which allow the pieces to be reviewed thoroughly by themselves and have tests to show that they each work.
- hcarvalhoalves 2y ago
  I guess this varies largely with project, stakeholder, etc. The kinds of projects I have been involved, showing a PR would’ve been either useless to communicate anything, or have to explain why it’s “throw away” and why we can’t ship the prototype. That’s why I stressed it’s an opinion piece but no data. Unfortunately in this industry we have a lot of experience reports, but lack actual data on what is or isn’t more effective way to work.

mrkeen 2y ago

As Lamport says: the algorithm is not the code. Not all products need an "algorithm" per se, but if your product needs to do collaborative editing or something else CAP-adjacent, that algorithm is going to need to live somewhere (not in throwaway code). The right algorithm (or even if such an algorithm is possible) won't be discovered via iterating on the code base.

bluGill 2y ago

Design documentation should be done on a whiteboard. You have limited space but that forces you to write down what is important and who it doing what. in a few weens it is so different from reality that you don't feel bad about erasing it for whatever is next.

simonw 2y ago
... as long as you then take a photo of that whiteboard, attach a timestamp and put it somewhere people can find it in the future. Otherwise it's not documentation at all, it's lost to the wind.
- bluGill 2y ago
  Chatis the point - it should be lost to the wind. I have never seen design documentation worth reading except in textbooks where it is only used to explain pattens to students.
  - simonw 2y ago
    Right, and my point is that this stuff genuinely matters and is worth recording - but needs to be recorded with a very clear timestamp (hence my preference for comments in a GitHub issue or PR). Otherwise you'll inevitably find yourself re-litigating old decisions because you never recorded WHY you chose one approach over another.
    - bluGill 2y ago
      Why is important but that is a very different thing from the desing documents I used to have to write, those would not tell you why.

theptip 2y ago

Aka “Ready, fire, aim” from the Pragmatic Programmer. This approach is fine but make sure your iterative prototyping is refining some sort of e2e / acceptance test, with good comments / README describing the intent. It’s really easy for the prototype to end up being shipped and painful refactoring happening once you’re successful. For me, a lot of the time this ends up being a question of what is known vs unknown. If you have a clear customer requirement but technical uncertainty then iterating on prototypes is usually better. If you have unclear customer requirement then shipping MVPs iteratively is usually better. If you have organizational uncertainty (eg you need to compose components from multiple teams and align roadmaps, as is common in big companies) then the design doc is often the place to start.

softwaredoug 2y ago
I totally agree. The prototype being shipped is the #1 risk. And why even though I prefer this approach, it may be impractical if organizations can’t be disciplined.
- kmoser 2y ago
  If you have time to rewrite the prototype twice, you also have time to write and maintain the documentation which would have made it unnecessary to rewrite the prototype twice. Not saying iterating the code is always bad, but it shouldn't be a substitute for sufficient up-front planning that would have saved programmer time. And yes, the prototype usually ships. There is often not enough time to completely rewrite it, let alone fix all the bugs and add all the necessary features.

deleted 2y ago

[deleted]

wavemode 2y ago

The design document is for documenting what problems you're trying to solve, and (critically) what problems you're not trying to solve. And the relative advantages and disadvantages of competing approaches. The mistake people make with design documents is going into too much detail on -how- you're going to solve the problem. That's where prototypes ("throwaway code") come in. The design document should just be a high-level overview.

RexySaxMan 2y ago

Being open to throwaway code before a design doc+review is an idea I promoted and tried to demonstrate in my projects at my most recent employer, but I found that it just didn't work within our engineering culture an expectations. Funnily enough, it had the most success when working on larger projects that spanned multiple teams and services, where often my team was consuming or providing an interface, and the code sample provided a clear usage pattern that other teams could critique or grok. I got the most dysfunctional comments within my own team on smaller projects and PRs (e.g. "not sure why you want to do it this way" on small code blocks, critiquing data structures used), so I'm still not sure if it was a company culture issue or team issue.

liontwist 2y ago

Which is cheaper? A change in code? Or a change on paper?

teamonkey 2y ago
A change on paper which needs to go though various approval stages, tasked up and finally implemented can be much more expensive than a change in code. Or the opposite.
- liontwist 2y ago
  I absolutely agree. And the other comments here have pointed out the danger of code is that someone will want to ship your draft. So business processes can kill either one.

allenu 2y ago

I'm a big fan of prototyping to explore a problem space. I think some initial design sketches are useful, but you often reach a point where you can only learn by implementing. I've encountered so many design constraints in the past that I couldn't have planned for, but perhaps others are better at comprehensively thinking through a problem space than I can. I agree with the blog post that doing a hacky solution is very helpful to understand the problem space better, although I think it's something that's challenging in an organization. In a lot of orgs, it might be viewed as a waste of time to work on something hacky. It could also come across as wasting people's time by engaging in too many discussions over PRs. People want shipping solutions today, not explorations that might need to be rewritten later. Asking for feedback might also come across as someone being unsure of a solution and needing "help" on it. The dynamics of working in a team generally nudge devs to make more conservative moves and writing more up-front design docs, which will be slower and safer. I'm not arguing that's a bad thing, though. You need the documentation to communicate intent across an org and many other people will need to pick up the work, too. A PR may not provide enough space to comprehensively explain the overall design. As an indie dev now, I find sketching some designs, followed by prototyping, then "massaging" the prototype into a working, shippable solution the ideal workflow. However, it only works because I'm solo and don't need to worry about getting an okay on potentially risky solutions or having to communicate and get buy-in on implementations. In a company that has lots of other devs and lots of paying customers, I wouldn't be able to do things that way, and for good reason.

damethos 2y ago
> In a company that has lots of other devs and lots of paying customers, I wouldn't be able to do things that way, and for good reason. Why not? You do the "sketching/mockup" of most of the flow (without going into too much design detail) in order for the team to understand better what you are going to build. Then, everybody can provide feedback based on their perspective, do a couple of iterations, then prototype (which if done well will be the initial version of the shippable solution) and then iterate again.

jnsaff2 2y ago

"Plans are worthless, but planning is essential".

CharlieDigital 2y ago

No. Just no. Design docs should capture reasons. Even if the code is throwaway, the reasons for the flow and process modelling for the use case don't change at the core. Some implementation details might change and the design may certainly also change accordingly, but the process is generally stable. That's what should be captured in design docs.

jasonpeacock 2y ago

This is called prototyping, which is a valuable part of the design process; some people call it "pathfinding". These are all inputs into the design. But a design is still needed, of the appropriate size, otherwise you're just making things up as you go. You need to define the problem your are solving and what that solution is. Sometimes that's a 1-page doc without a formal review, sometimes it's many more pages with weeks of reviews and iterations with feedback. Don't forget: "weeks of coding can save hours of planning" ;)

sevensor 2y ago
Agreed, why not both? In fact, I’d say, first write up a theory, then demonstrate that it does or does not work using a prototype, then write the actual design doc. At all times, and continuing into the implementation phase, prioritize the disposability of your code. The easier it is to delete, the better.
- softwaredoug 2y ago
  I think my argument would be that they could be the same artifact. Hence my usage of Draft PRs with a lot of rich documentation. And a willingness to throw it all away if you don't think its ultimately the right approach. The real problem is the industry's inability to throwaway first solutions, so we introduce this (IMO inefficient) 'design doc' step as a safety mechanism
  - makeitdouble 2y ago
    I enjoyed the writeup and think it's a nice idea depending on the situation, but with serious limitations (for context, I also do prototype first, but still right a design doc at some point) The main issue to me is exactly that we do throw away the prototype implementation. Writing rich documentation for throwaway code is tedious, and at the early stages I see a split between the people that mostly read the doc and only glance over the code, those who almost ignore the docs and focus on the code, and some rare people actually looking at both and getting confused at the discrepancies ("you say you in your doc you store values in the remote database, but this code only writes to the local one, which one will stay ?") Perhaps I'm just not good at docs, but doing code heavy prototypes with only very light and high level doc was way more efficient. Then when we settle on one direction, I can freeze the main points in a separate documentation and rewrite the prototype in a more serious version. Having a separate design docs also helps when the system components are split across many area. Having the doc even when it's a compact proposition standardizes the process and you never have to ask upfront if it will be needed or not.

sesm 2y ago

Prototypes discover constraints, docs document them (as well as what problem is being solved, what solution was chosen under those constraints and what are consequences).

starkparker 2y ago

> Another important point is on using PRs for documentation. They are one of the best forms of documentation for devs. This feels true, and also why design docs are important for projects that involve roles beyond software development, where PRs can be among the worst forms of documentation.

patrulek 2y ago

Design docs are only as good as your knowledge about the problem you want to solve and knowledge about tools available for solving it. If there are more unknowns than knowns imo its better to start with prototype to explore problem first and then eventually come back to planing.

djmips 2y ago

I wonder about all of the best inventions of all time and how many came from prototyping and how many were the result of a real peachy design doc.

rsanek 2y ago

almost every single time I've seen 'prototyping' done that was originally intended to be throwaway, it was ultimately the basis of the actual implementation.

rsanek 2y ago

the idea that you can get value from just creating draft PRs without integrating them at all does not match my experience.

ChrisMarshallNY 2y ago

The biggest issue that I’ve had with design docs, is that nobody reads them; even if required by their employer. The biggest issue that I’ve had with prototyping, is that people consider it “ship” code, and force me to use it as final code. I find that I’m best served with a hybrid approach, where I spend a lot of time planning and documenting, but basically, for myself, then writing ship-Quality prototype code, so that using it in the end product is OK.

kccqzy 2y ago
The reason people don't like to read the average design doc is because the average software engineer doesn't have enough writing skills to express the concept clearly and concisely without editing. The design doc becomes a mumble jumble of raw notes that nobody really understands except the author. And then people dread reading this kind of raw notes. However, if someone tells that design doc writer that this is something like a term paper at school that is being graded, they can actually improve their writing by quite a bit by doing some editing. So the symptom is really the same as prototyping: people write draft-quality design docs and magically hope it to be a good quality piece of writing suitable for a wider audience. What they need is a few rounds of editing, just like when they write prototype code they need a few rounds of refactoring.
- mianos 2y ago
  As much as I get frustrated with GPT4's limitations when it comes to code, it's quite good at expanding detailed bullet points into solid design prose. You still have to read it back and triple check it, as you would your own work, but you don't need all the time it takes to extensively expand it from draft. Also, which it is in context it's quite good at documenting what needs to be done to test it.
  - ChrisMarshallNY 2y ago
    I agree. I have used it for just that.
  - pclmulqdq 2y ago

krisoft 2y ago

I like the idea and we use it at work often. One pitfall one has to be aware is that it is easy for the people who are asked to provide feedback on the prototype to get bogged down in the details. What you want is people to squint and tell you if they like the general approach, but what often happens is they tell you that you need more unit tests and you could use a ternary operator here and here. (The particular details will of course differ in each case.) The reason for that, in my opinion, is that your thing looks like a PR and therefore people default to the kind of review they do for PRs. But since this is a different beast it needs a different mindset during review. And of course the only possible solution for that is proactice and active communication to get everyone on the same page.

jp57 2y ago

We imagine software efforts that go through a clean, neat flow: We write a design doc. Then make small incremental changes in a PR to rollout the functionality. Our git histories look clean and orderly. Like a steady march of progress. Who imagines this? Professors who teach software engineering classes? This reminds me of people who think that you write prose (essays, stories, novels, etc) by writing an outline and then "filling it out" with prose, as if in the process you will never discover anything that requires you to rewrite or restructure the document. Nobody writes that way. First drafts are always terrible and basically all good writing has been heavily revised. Writing code is much more like writing than it is like building a house or a bridge.

throwaway2037 2y ago
For myself, I always find great value in debugging new code that I have written. Something about stepping line by line through new logic, and viewing variables/memory really helps me to improve my code. "Oh, I don't need that local var." "Oh, I should add a temp var to make the code easier to debug here." "Oh, this code is weird when the collection that we iterate is empty." No matter how old I get, and no matter how much code I write, I always discover new things when I debug my newly written code. I guess this could be compared to an author writing a first draft, then going back to read it... or reading it aloud to themself or another person.

robertclaus 2y ago

In my experience there is a MASSIVE difference in the type of feedback someone gives on code vs a design. A design doc encourages "why" questions to get everyone thinking about the problem space. For example, a design doc comment might be "why are we suggesting a Rust Webserver when nobody in the company is proficient in Rust yet?". In my experience those more subtle questions are much harder to raise once a prototype is working - "why does the team's experience matter? look how great it works! If you don't block it we could get this to production in a week by just polishing the prototype!"

bawolff 2y ago
This is not neccesarily a bad thing though. Lots of "why" questions are really counterproductive bikeshedding. Especially when it comes from just reviewing a design as opposed to working code.

designAndCode 2y ago

Preferring throwaway code over design docs (softwaredoug.com) is a Horrible take on software development.

baazaa 2y ago

A lot of my code takes in garbage data and does some complicated stuff to produce useful outputs. Almost all the difficulty comes from hidden problems in the data upstream, including very often the data contradicting itself (a lot of fuzzy matching, 'voting' to determine the truth, etc.) None of these problems are ever-known beforehand, and can typically only be discovered after a lot of work has been done to make the data more intelligible (i.e. in the process of writing of my code). I've realised over time that everyone else who prefers the design-doc approach refuse to do work like this. There's just a whole class of problems that are too hard without prototyping.

softwaredoug 2y ago
Right I feel like the problem isn't "prototyping is bad". Prototyping is good! But sadly many companies and devs aren't disciplined enough to throw away first solutions. And that's the real problem. And its not just the companies, developers get too attached to their first solution, rather than using it as a way to discover knowledge. Companies need to reward knowledge discovery, not just "shipping to prod"

rich_sasha 2y ago

I think the key is to have a solid understanding that this is throwaway code. I know of, erm, one quite company, fairly well known in its big industry, where indeed no one gathers any requirements and a junior guy is told to type it all in - with the view that it's probably 90% correct and the rest can be ironed out at some stage, or at worst rewritten. But what tends to happen is thus: 1. The first draft tends to address all the wrong problems, doesn't abstract the right things, is over and under engineered in all the wrong places. Fine, it's a draft I guess 2. But here's the kicker: unless it's really unusable, there is now pressure on users to accept the draft, because changing it, perhaps substantially, requires work, and as it it sort of kind of works, if you squint. And this thing is there and you can pretend it's a job done. I think ploughing in to writing code works if you ha r a decent idea of what you need to achieve and what the pinch points are. Without that it can be quite an expensive and frustrating approach.

gigel82 2y ago

If doing greenfield work, planning sounds nice, but if you're integrating with crusty / legacy systems that are poorly documented (if at all) planning is a waste of time; you'll end up saying "Library X will do Y" a lot only to find out none of that works the way you thought. So for brownfield, I may have a plan (written down or not) but it's mostly code (some throwaway) just to uncover how things actually work.

jwcacces 2y ago

But with without design docs, how will my hordes of low cost contractors know what to do?

nhumrich 2y ago

Design docs are incomplete without reference implementation code. Which would require you to actually follow this process.

w10-1 2y ago

Opinions sans reputation or data can still be helpful when they identify the landscape and issues, e.g.,: A main goal of design is to identify what's not feasible through logic. So much easier than prototyping. But still "can it be done?" is a far cry from "can we do it?". The benefit of prototyping is to show that something is possible. There the key question is integration: can persons Pn make code C on system S that meets both goal X and constraint Y - i.e., a design as product development. Leaving aside bad-faith behaviors, the real question is socialization: 1. how to gather collective wisdom in some relatively natural and encouraging manner to encourage collective deep consideration of hard problems to avoid waste and get things done. And 2. the same for motivation: getting everyone aligned, understanding their role and the quality/schedule risks. Given the uncertainties and costs of product development, the prototype has significant advantage of seeming "real" relative to some "ideal" solution, and thus can bias teams to the concrete, particularly when issues are contended. Prototype-driven planning likely reflects lack of organizational cohesion (and ironically kicks that can further down the road). So generally I see prototyping as validating designs, and try to make the design discussions lean enough to engage otherwise-prototyping engineers.

llm_trw 2y ago

What I've found is that there is no such thing as throwaway code if you share it with anyone. I've had code I threw together in 10 minutes end up in production after putting it in a 'temporary' repo.

bdndndndbve 2y ago
For a greenfield project that's fine - solve the issues that come up as they come. Someone is getting value right away. Code you throw away makes the most sense to me for prototyping cross-cutting features in existing systems. A lot of companies can accumulate a ton of crud in only a few years of development time, and it follows Conway's Law that the crud is shaped like the org tree. Writing a throwaway feature end-to-end helps to identify the interfaces between the teams and subsequently components of the software. This is also why I'm a big fan of assembling project teams over having teams "own" an area. Everyone on the project team is responsible for the project working well. Otherwise every team is worried about their small domain.
- llm_trw 2y ago
  This is how green field projects become brown field projects in 4 weeks.

bdd8f1df777b 2y ago

Design docs are critical to your promotion. The boss and the committee do read your design docs, sometimes very carefully. Only your peers and at most your TL read your code.

klabb3 2y ago
> the committee do read your design docs, sometimes very carefully Yadda yadda, that may be true sometimes but that the quality of the doc would get you promoted makes no sense and is also not a good metric. I think most of these committees look at who approved it and what known people thought/wrote in response. I was told in this promo-game to try to get comments from high-level people for this reason. That is more a popularity contest, and less a competition of well articulated ideas. I think most people here want to improve the way things are. We talk about engineering practice to improve the practice, not to please management or give career advice. Usually, at least. This is where it happens first. A bunch of engineers (or just generally people with boots on the ground) get together and find better ways to do things. Before agile was mainstream and corrupted beyond recognition, the waterfall model was the way recognized by management and working within that model would have gotten you promoted easier. Things evolve.

m1n1 2y ago

We had to build and launch something by a deadline in order to avoid renewing a contract that would have cost $x mil. But we discovered we weren't going to finish in time with the resources and the approach that was planned. So I got approval to hack out a temporary impartial suboptimal version and we were able to take off in time. This has allowed us to fly for a bit while others finish building out the permanent proper version of that part of the wing. In fact, during our flight we discovered missed requirements in the original design. This has delayed that proper version's release to prod. But I've been able to add that quickly to my hack and keep us flying. My hack doubles as a production support tool. And as an alternate route if the permanent version needs to be paused because of a bug. Yes it's a partial imperfect hack but it has benefits. Someone has complained about the language I used since it is less common. But remember, we weren't going to be able to take flight with the existing resources and approach. We would have needed more and/or faster developers in the favored language to meet the deadline. If any present employee (including me) had bandwidth and was able to be as productive in the favored language as I was building my hack in the uncommon language, that employee would have been tasked to build the permanent solution on time. That option was not available. Anyways, if you have an existing production support tool, it's also a place where prototype features can live for a while.

Aditya_Garg 2y ago
What was the language?
- m1n1 2y ago
  I think it's not uncommon for a dev to be faster with one language than another. And for another dev to know the same two languages but be more productive in the opposite direction. (And I am mindful that the bar was much lower for me -- being a temporary hack, my stuff didn't have to integrate fully or have the same level of production manners) But here are two factors that make me faster in the uncommon language. You know the usual debugger experience where if you keep stepping or you set a breakpoint and then later realize the interesting part is actually behind you? Which means you have to start your scenario again? Well, the uncommon language has a recording debugger so you can visit any points in front of or behind you, and see what any variable or return value was. You're not limited by the current stack because the recorder captured every package you told it to from the beginning Even a third party package... This means I only have to debug once to find the bug, not n times. And the language is expressive and pliable enough that this debugger was implemented in the language itself... And mostly by one guy -- not me of course -- it didn't take a whole company to implement it. And you know how in some languages like Java if your car (program) starts acting up in LA, you have to update the blueprint, send it to the car factory, build the new car, drive it back to LA, and try the same left turn to see it it still ferks? With the uncommon language, I can stay in LA and change the car while the engine is still running, n times before the 2nd Java car arrives. The language is Clojure.

agentultra 2y ago

I'm kind of on the fence about this approach. In the worst case you end up wasting time on a lot of dead ends. It's in such a situation that I kick myself for not spending time thinking about the problem before starting to write code. The best times I've had with writing design documentation has been when I thought about the problem enough that I could specify the properties necessary for a correct implementation. Depending on the scope of the problem I might use property tests or model checking. In any case, thinking about the problem up-front tends to prune away dead-ends before you head down them. (Of course, you can't do much about a bad specification except try to avoid them... learning how to write good ones takes experience, wisdom, and constructive input from knowledgeable colleagues). Update: I’m on the fence because I’ve also had a lot of success with implementing partial solutions: just get something good enough that works for some use cases and improve as you go.

Nezghul 2y ago

I wish my employers would value throwaway code or design docs.

charlie0 2y ago

This makes me shudder because I've never seen this done in practice. What always happens is the code builds up like Jenga until no one wants to touch it.

hasbot 2y ago
And it's so obviously bad that new hires want to re-implement from scratch even though they don't have complete knowledge of what the software does.

hulitu 2y ago

> Preferring throwaway code over design docs Why writing it if you trow it away anyway ?

ozim 2y ago

I don’t have link handy but one of the good talks that is posted on YT is about explaining how writing code is the „design phase” and not what a lot of people think „build phase”. Build phase happens at the compile time and at runtime.

nertirs1 2y ago

I have been moving towards integration tests as documentation approach, because in a fast moving environment anything that is not constantly verified has a tendency to become false.

hitchstory 2y ago
How do you do that? Im curious because I wrote a framework for this (same name as my username) but when I talk about the idea I receive a sea of blank faces.

bfung 2y ago

Except, how long does it take to throw the code away? Sometimes never. Write short designs; Goals, constraints, options. Prevents the tech debt from building over time and signals better when to throw chunks of systems away.

marcyb5st 2y ago

I don't agree. I believe that when the solutions' space is big design docs work best. If they are done correctly they are a (shallow) breadth-first search in the space. Specifically if in your design doc include "alternatives considered". Additionally, having multiple people looking at your doc you can prune some possible paths. A breadth-first search is useful when you don't know much about the intricacies of the problem/topic at hand, and so you need some ground work to take informed decisions. If, instead, the solution space is narrow then by all means do a prototype/throwaway PR/... to validate the approach.

gareve 2y ago

I think it all depends on the size of the team. Very small team and too many design docs, not good. Huge team, multiple timezones, multiple squads, and few design docs, not good either. And then you balance with all the values in between depending on your team size & culture. Even within the same company, your approach will/should change as it grows. There's a critical point where move fast and break things approach will eventually end up with too many outages, production bugs, unpolished/confusing product, and last but not least, FTC eye watering fines.

LAC-Tech 2y ago

I find myself researching and thinking a lot more about things before I actually program these days. It takes longer before I write, but my code is shorter and more to the point. I don't think I'm personally capable of explorative coding. I get too lost in the weeds and lose sight of the problem.

deleted 2y ago

[deleted]

throw4321 2y ago

Does your task need great code? Not a rhetorical question. Often the goal is the functional minimum. If that's your gig, it's hard to appreciate code quality maximization, and vice versa. If you do maximize quality, I'll one-up the suggestion in the article. Treat your first write as throwaway code. And your second. Up until the point where the rewrite would be roughly identical. It's basically early refactoring, but with the code at its freshest in your mind. Coding it the first couple times implicitly maps out the problem domain. You also leave no internal technical debt on the table. A surprising amount reveals itself right after you wrote it in. It gnaws at your ability to proceed. Subconsciously, it splits your attention in two: how the code is and how it should be. With each "fail" your attention spreads out and thins out. Finally, this habit makes you more fluid in the language. Quality-maximized code takes longer, but your actual typing rate ends up being much faster.

nerder92 2y ago

So we are basically re-discovering XP practices? (http://www.extremeprogramming.org/rules/spike.html http://www.extremeprogramming.org/rules/spike.html)

beart 2y ago

When a stakeholder comes back 6 months after project launch complaining about missing/incorrect features, I can't use throwaway code to prove the project was built to spec.

iamalexm 2y ago

Design docs are great for high-level orientation. If you are laying out all your code structure around it, you are doing it wrong. It's great to use the for what patterns will be used (using a facade pattern for example). It gives eng's a guide to how to implement at a high level and it should identify points of non-functional requirements; speed requirements, monitoring, security, etc. Throwaway code doesn't even touch on that. It should also put in scope some of the architecturally significant decisions that need to be made. While throwaway/prototype code can address some of that, it doesn't always identify it and talk about _why_ it is important. In short, doing both is the best thing you can do and you should scope your design docs correctly.

dozzman 2y ago

The critical objective either of these approaches is aimed at achieving is helping you _think deeply_ about the problem; how that is best done largely depends on the software engineer. I feel design docs are a way to ensure that you indeed think through a problem as much as they are a tool for peer review. If you wen't through a fairly standard educational system, it's not unfamiliar to use writing as a way of thinking more deeply about a problem and communicating those thoughts with others (namely your teacher) -- a design doc is no different. This can fail when design docs are written as templated box-ticking exercises and address more superficial technical questions than the core problem of course; it actually needs to address the problem and that is very contextual in my experience. However some folks are just better at solving problems with a more hands-on approach, in which case throwaway code may be more effective. If that is you then go for it, though its likely you'd need to still need to write _something_ to either document changes or communicate your decisions/trade-offs with the rest of your team. Fundamentally just do what allows you to solve problems best and take into consideration how to best work with your team. There is no one-size-fits-all solution to _thinking_ and broadly no-one cares how you work (I believe, I mean I certainly don't) if you're efficient, communicate well and get the job done to a high standard.