I think that many companies are standardizing a workflow, that before writing any code you need to write a

design document

with the options on how to solve a problem and the chosen solution. A lot of times this document has the code changes required by any of the solution options. To me the options that we didn't end up following seem as valuable as the chosen option, and those options should also be captured in code. A really easy way could be in separate branches, but then we loose visibility of them. Is anybody familiar with source control software or with patterns to work with source control that also keeps tracks of options considered but not followed at the end?

I can confirm regarding design documents (we called them Tech Design Docs - TDD - not the best name since it is confused with test driven development). Regarding documenting different options, usually we would consult the TDD or ask somebody, which is certainly not very approachable. And if there was a clearly better alternative to implement something, usually we would describe it in TODO comment next to the implementation. However, I wonder how often somebody really asks (why wasn't this done in this way), from my experience, I haven't seen that happening very often, at least not at the degree where reviewing all the previously considered options would be useful. But it does happen sometimes, and then TDDs usually worked out (but with lot of digging, figuring out the latest one and so on). Just thinking out loud, I might on the other hand find it useful if they were more available, but it is hard to imagine right now.

Yeah, I'm not aware of existing solutions, but this is a problem I've often felt and tried to hack my way towards. On my projects I use a system of layers so that I can keep track of past versions with fewer features. And continue to keep them working in CI: http://akkartik.name/post/wart-layers. Layers form a linear sequence, and I've often considered introducing branches. But I've never found a strong concrete use case and clean way to do this. One easy approach may be branches as you mentioned coupled with links to those branches (on GitHub or wherever) sprinkled in a few key places that the branch modifies. I like links 🙂 (https://futureofcoding.slack.com/archives/C5T9GPWFL/p1592285060323600?thread_ts=1592252831.319600&cid=C5T9GPWFL)

I've been thinking more recently of a code project as a set of knowledge in a domain or to solve a problem. I wish this knowledge could not only be on the final decisions but also on wrong decisions and the paths not chosen

It sounds like you want to distribute branches (makes me think of multiplicative distributivity, anyway) down to the source file or function level, or something like that? That seems like an interesting idea. The fundamental obstacle in my view is that a lot of those roads not followed will, by nature, affect the design of large swathes of the project, like whether certain files exist at all. It might be that the best thing is to add annotations, uh, somewhere, about where those branches' existence should be surfaced in the VCS or code browsing UI. E.g., somehow when you're looking at the router for your REST API, there's a button that shows the branch where you tried gRPC.

You're right that many alternatives may require pulling in more changes. But not all. There's lots of value in simpler scenarios. For example, here's a self-contained alternative in a code comment that I've found useful for 10+ years. https://github.com/arclanguage/anarki/blob/0913288ec1477f2598e8095a2b5e9b14eb97dc4e/arc.arc#L662

Good point (and nice example). It might be easy to just branch on the size and scope of the diff when deciding whether to show it inline. Less than 20 lines and all in one file? Just show it, otherwise put it behind a button.

that's a great example @Kartik Agaram. Saving that info in a comment looks like a great hack, but also makes me sad not having a nicer way to do it 😢 Your example also made me think of having benchmarks against "branches", as performance could change with upgrades of packages/language or rewrites of other parts of the codebase 🤔

Yeah, performance is a common scenario here, or to be precise how performance interacts with complexity. On many occasions I've seen someone introduce a lot of complexity for performance, but the measurements that drove it are never revisited. Eventually we find that the performance benefits no longer accrue, while the complexity cost continues to be paid. Ideally we'd be able to constantly track performance benefits of the trunk over alternatives. Using our existing CI system.

I secretly hate that now is so common to run everything in a CI server 😂 , but yep I can see how it can be useful doing performance benchmarks in multiple branches. This convo has been great @Kartik Agaram, I got so many good ideas from it!

This kinda goes in the opposite direction than the rest of the discussion, but besides design documents, there are Architectural Decision Records (ADR). They are more lightweight, less focused on the implementation details and more on the reasoning behind the decision. In a nutshell, it's just a problem statement, the context (current state of the code and organization), driving factors, analysis of options (pros and cons), the decision, and the consequences. I use ADRs for larger-scale decisions with multiple stakeholders and conflicting priorities. One thing I find useful is that ADRs capture the current organizational context which is ephemeral and is never recorded otherwise. Examples might be (1) one team is overloaded while another one is idle, so we might lean to the solution that utilizes their expertise, (2) the other team in the organization is developing a similar solution, so we might piggyback on that program, but that adds an additional dependency on the other division, and we know they are slow to react.