Hacker News Reader

Comment by brendanmc6 | Hacker News Reader

I think you are confusing the spec as "this is how it must be built", as opposed to, "this is what the software must do and must not do to be acceptable".

To me saying "the code is the spec" is like saying "the business wants it this way because that's how the code is written". Which is obviously backwards.

Does the business mandate we use a cache for this hot path? No, but the business set performance targets, and the cache was a sensible way to satisfy them. See the difference?

I believe that the 'musts' and 'must nots' deserve special attention, and need to be recorded well before I decide on the 'how'. Every team does this differently. I find that writing itemized, functional acceptance criteria is practical way to marry the two domains. I also think the process matters a lot more now, because the temptation to let an agent ship it is increasing and the tedium of maintaining these specs is decreasing.

View on HN

> Does the business mandate we use a cache for this hot path? No, but the business set performance targets, and the cache was a sensible way to satisfy them. See the difference?

This seems confused. Specs are free to include as much or as little detail as they deem necessary. If a spec only wants to suggest vague performance goals and handwave the details, that's permitted. But if specs want to specify the exact means by which performance will be guaranteed, that's also permitted. And this isn't an anti-pattern, this is often very useful. For example, plenty of APIs in the real world specify algorithmic upper bounds for time and space consumption, which is useful in that they allow downstream consumers to have a greater understanding of what sort of performance their own systems will exhibit despite the API itself being a black box in other respects.

So the answer to the original question definitely isn't "no", it's "maybe, depending on the sort of guarantees we want to provide to our users".

I think we are actually saying the same thing! We could think of situations where the cache would be verboten (sensitive info), or where it would be mandatory, like in your example, or optional like in my example.

My aim was to voice disagreement with the "code is spec" crowd, whom I think are using a different (and in my opinion tautological / useless / counterproductive) definition of spec. Probably because they are mad that I use trigger words like Vibe and Maxxing, and they assume I can't even read the code I'm shipping. I digress.

In your "time complexity is a downstream requirement" example, which is a great one, I think you would prefer to have well-maintained written documentation of that criterion that lives outside of the procedural code itself, would you not? How much attention that doc gets is a matter of process and preference, but I'm advocating it should get more (spec-first).

> In your "time complexity is a downstream requirement" example, which is a great one, I think you would prefer to have well-maintained written documentation of that criterion that lives outside of the procedural code itself, would you not? How much attention that doc gets is a matter of process and preference, but I'm advocating it should get more (spec-first).

That is a huge mixed bag. It helps to have an high level overview of an algorithm. If you want to be very accurate about an algorithm, then that documentation is potentially harder to digest then the actual code. I personally don't even know how to express an sophisticated algo in natural language without falling back to pseudo code. Then you also have to verify a purely natural language defined algo with a very slow feedback loop (agentic PR cycle) against a test. Which seems to be a guarantee for myself to get sloppy because it's annoying.

There are a lot of reasons to theorize about algos in spoken or written natural language. For me it's questionable why you'd prefer the natural language to be the reference implementation when all you want is the code. That only makes sense if you never want to look at code.

You're just conflating NFRs with spec.

Structuring your codebase like it's your spec doesn't mean you're omitting the NFRs - they need to become part of your codebase too where applicable.

eg with your first example of response times - in javaland you can use annotations on the REST resources and RPC endpoints

or your second example with specific data that may not be cached via a combination of AGENTS.md in the directory of the module providing access to it, potentially doctexts on the data constructs in question and QA agents which run pre review and raise (and resolve) the inevitable violations. Which I may add will _also happen, and so much more frequently_ when you're doing "spec driven development" via markdown files.

The difference is just down to code being testable, and markdown/yml being purely "trust me, it's like this fr fs man"

However you want to structure your spec, just structure your code like that - it works way better, because llms can handle source code so much better then markdown files.

It's not going to pass the "enterprise architect" review job application of the last decade, but your project will work, much much better and with less input required by the developer... And your development process is less let's roll the Dice and more this isn't the spec yet

> I think you are confusing the spec as "this is how it must be built", as opposed to, "this is what the software must do and must not do to be acceptable".

You can't enforce a "do not do this" to an LLM. Just putting it in the context by saying "don't do this" makes it more likely that it will eventually do that.

Yes, I agree. If you tell humans "do not think of pink elephants", they are more likely to think about pink elephants.

Therefore, you must not use humans for any important work.

> Yes, I agree. If you tell humans "do not think of pink elephants", they are more likely to think about pink elephants.

> Therefore, you must not use humans for any important work.

Counterpoint, all important work done in the history of humans were done by... humans, and yet I see no pink elephants created as a result of telling humans "do not think of pink elephants".

I’ve seen loads of very bad/wrong code written by humans

> I’ve seen loads of very bad/wrong code written by humans

Have you seen any pink elephants?

Yes, I see them all the time when I drink lots of alcohol [1]. This is a common issue with humans called "hallucination" which proves that humans are unreliable.

[1] https://en.wikipedia.org/wiki/Seeing_pink_elephants

> I think you are confusing the spec as "this is how it must be built", as opposed to, "this is what the software must do and must not do to be acceptable".

You are confusing code with application code. The latter thing you describe is a test, which is expressible in code.

> To me saying "the code is the spec" is like saying "the business wants it this way because that's how the code is written". Which is obviously backwards.

Not only is it backwards, it is a belief that is completely wrong and detached from reality. More often than not, implementations contrast with business requirements both in terms of bugs and gotchas.

Also, it's laughable how code is depicted as the realization of any spec when the whole software development sector is organized around processes that amount to improvising solutions in short iterations.

Reply on news.ycombinator.com