[HN Gopher] Preferring throwaway code over design docs
___________________________________________________________________
Preferring throwaway code over design docs
Author : softwaredoug
Score : 122 points
Date : 2024-12-14 14:52 UTC (1 days ago)
(HTM) web link (softwaredoug.com)
(TXT) w3m dump (softwaredoug.com)
| dboreham wrote:
| 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 wrote:
| 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 wrote:
| A few more years, and same here.
|
| Design _discussions_ can be very useful though.
| jprosevear wrote:
| 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 wrote:
| 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 wrote:
| 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.
| JKCalhoun wrote:
| Yeah, that sucks for management. Not my problem. ;-)
|
| In fact more or less everything that I have found burdensome in
| the last decade or so of my career were things introduced to
| satisfy management.
|
| Unit tests? Code coverage? For management peace of mind.
|
| Code reviews? I'd argue, same.
|
| Agile development (obviously).
| miscaccount wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| As they say,
|
| > Build one to throw away (You will anyway)
|
| (Probably first phrased "plan" by Fred Brooks)
| JKCalhoun wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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__ wrote:
| 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 wrote:
| 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.
| __MatrixMan__ wrote:
| I like where your head is at but if you keep it to
| yourself then you can't get feedback on it.
|
| I once did the draft with ncurses as a hedge against it
| becoming the real thing. It didn't go over especially
| well but it was fun.
| appleiigs wrote:
| I had a boss who had a math degree. He'd map out the flow from
| start to finish on a whiteboard like you see mathematicians on
| TV/movies. Always had the smoothest projects because he could
| foresee problems way in advance. If there was a problem or
| uncertainty identified, we'd just model that part. Then go back
| to whiteboard and continue.
|
| An analogy is planning a road trip with a map. The way design
| docs most are built now, it shows the path and you start
| driving. Whereas my bosses whiteboard maps "over-planned" where
| you'd stop for fuel, attraction hours, docs required to cross
| border, budget $ for everything, emergency kit, Plan A, Plan B.
|
| Super tedious, but way better than using throwaway code. Not
| over-planning feels lazy to me now
|
| Sure, everyone has a plan until you get punched in the mouth;
| however, that saying applies to war, politics, negotiations,
| but not coding.
| huijzer wrote:
| Yes I have to second that. MLJ.jl is also written by a
| mathematician and the API is excellent. Truly well thought-
| out.
|
| (If you think "why does MLJ.jl have so few stars?" please
| keep in mind that this library was written for the Julia
| language and not for Python. I honestly don't think the
| library is the cause of low popularity. Just wrong place
| wrong time.)
| jnsaff2 wrote:
| I the book How Big Things Get Done they analyze big and small
| project failures and success and end up with something along
| the lines:
|
| 1. Spend as much time in planning as necessary, in the
| context of mega projects planning is essentially free,
| maximize the time and value gained in planning.
|
| 2. Once you start execution of the plan, move as fast as
| possible to reduce likelihood of unforeseen events and also
| reduce costs increases due to inflation, interest paid on
| capital etc.
|
| [0] https://www.goodreads.com/book/show/61327449-how-big-
| things-...
| SaltyBackendGuy wrote:
| +1 for "How Big Things Get Done". It changed the way I run
| projects. I got lucky in the sense that I was able to
| convince my corporate overloads to allow us to have
| separate Discovery and Delivery goals, on the premise that
| discovery is cheap and delivery is expensive (the former
| significantly reduces risk of the latter) and we show our
| work. Discovery goals come with prototype deliverables that
| we're ok not shipping to production but most times lay the
| foundational work to ship the final product. Every single
| time we've found something that challenged our initial
| assumptions and we now catch these issues early instead of
| in the delivery phase.
|
| We've fully embraced the "Try, Learn, Repeat" philosophy.
| CuriousSkeptic wrote:
| > convince my corporate overloads to allow us to have
| separate Discovery and Delivery goals
|
| Since I'm in the middle of trying to do something
| similar, would love to hear more details. What kind of
| goals, whats the conflict?
| bravetraveler wrote:
| Man plans and executives laugh
| DidYaWipe wrote:
| I had to do this for a patent application, and likewise found
| it very useful for identifying holes in my thought process or
| simply forcing myself to do the functional design work up-
| front and completely.
|
| It was also great for brainstorming about every feature and
| functional aspect you can imagine for your product, and
| making an effort to accommodate it in your design even if
| it's not MVP material.
| bryanrasmussen wrote:
| >Sure, everyone has a plan until you get punched in the
| mouth; however, that saying applies to war, politics,
| negotiations, but not coding.
|
| hey, the EU just introduced this new regulation is the
| software version of getting punched in the mouth.
| ozim wrote:
| First you have to have smart people who will be able to
| foresee design issues.
|
| That's a bit uncharitable but following this line of thought
| - you also need those smart people to be confident and
| communicative.
| simonw wrote:
| 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/...
| kmoser wrote:
| 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 wrote:
| 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 wrote:
| 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/#do...
| hcarvalhoalves wrote:
| 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 wrote:
| 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 wrote:
| 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.
| bccdee wrote:
| Hard agree. I don't know if "design doc" is the right word--I
| call them technical analyses--but writing up a doc that
| connects business & product needs to implementation details is
| highly useful to get everyone on the same page in terms of
| requirements & deliverables.
|
| If I'm clear on the requirements & everyone else is clear on
| what I'm delivering, this is unnecessary. Sure, jump straight
| to prototyping. But this is rarely true for any serious
| project. There are always unknown unknowns that you need to
| tease out from the stakeholders, and a technical analysis is a
| great way to do that.
| rockemsockem wrote:
| It's also easier for all involved parties to read, whether
| they're technical or not, assuming you have some sections
| that explain things without relying on code.
| keypusher wrote:
| > If I'm clear on the requirements & everyone else is clear
| on what I'm delivering.
|
| That's a big 'if', and usually isn't possible without
| prototyping in my experience. What you're describing seems
| like something that would be written after a prototype is
| already done. Presenting a prototype (or iterating on
| multiple prototypes) is a better way to tease out unknowns
| than any document.
| redcobra762 wrote:
| It's more likely that someone who holds this belief will be
| able to move substantially faster _with_ an LLM, than it is
| that an LLM would take over this task in its entirety.
| simonw wrote:
| Sometimes the "data" behind this kind of article can be decades
| of personal experience.
| yen223 wrote:
| Throwaway code is better than a design doc precisely because it
| is a concrete example.
|
| Without something tangible like code to tether conversations,
| discussions over abstract designs invariably devolve into "my
| imaginary piece of string is longer than your imaginary piece
| of string" arguments that lead nowhere.
| mrkeen wrote:
| 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 wrote:
| 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 wrote:
| ... 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 wrote:
| 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 wrote:
| 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.
| theptip wrote:
| 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 wrote:
| 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 wrote:
| 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.
| wavemode wrote:
| 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 wrote:
| 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 wrote:
| Which is cheaper? A change in code? Or a change on paper?
| allenu wrote:
| 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.
| jnsaff2 wrote:
| "Plans are worthless, but planning is essential".
| CharlieDigital wrote:
| 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 wrote:
| 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" ;)
| sesm wrote:
| 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 wrote:
| > 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| the idea that you can get value from just creating draft PRs
| without integrating them at all does not match my experience.
| ChrisMarshallNY wrote:
| 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 wrote:
| 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.
| 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.
| krisoft wrote:
| 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 wrote:
| _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.
___________________________________________________________________
(page generated 2024-12-15 23:00 UTC)