The truth is in the code
Bertil Muth

BigDecimal calculateTotal(List<BigDecimal> individualPrice){..}

Hmm. Don’t you just mean “sum”? Why hide what you’re doing with a method? That leads me to think maybe you’re doing something magic down there. I would be rather sad if it it just iterates down the list and adds it.

“The system displays a list of gloves.”

Brr. Now you have a perfectly good general purpose shopping cart bound to gloves. This customer may be a glove shop, but why only sell your software once?

This response is going sound a bit weird to those who know me… I have advocated for a very similar approach to yours myself.

Documentation that non-technical stakeholders understand as well.

Hmm. And there we have a problem. Non technical snake holders.


They specify things in broad brush strokes around very concrete items.

Programming is all about handling every single damn corner case. Every one. It’s detail detail detail.

And once you have nailed down and recorded all that detail… Yes, the program _is_ the most concise and precise description of the requirements.

Anything else lacks precision or is much more verbose.

Good programs and Good Requirements should be as generic as possible, otherwise you end up with duplication all over the place and coupling and dependencies in very painful places.

What do we mean exactly by a “Non Technical” person?

Pretty much it comes down to “Someone focused on the concrete, and lacks the capacity for floods of fine detail, and struggles with deep abstractions”.

In cartography they have the Generalization Problem.

The world has way way way too much detail to meaningfully display everything on a map. How do automatically reduce the detail as you zoom out?

Programs are even worse than geography. This bit of land is geographically distinct from that bit a mile down the road. Programs are fractal and self similar. This method, up to a couple of template parameters, is _exactly_ the same as that method on the far side. In which it _should_ be exactly the same code.

I really don’t believe it is possible or even desirable to automagically extract requirements from code.

I do believe the requirements should be stored as marked comments interleaved with the code that implements them.

And you can have a tool that strips out the code to feed the requirements the “non technical users” and a tool that diffs their changes to give a loose indication where the code needs to be changed.

Some requirements are in the form of data tables or enumerations…. yes, those should be extracted from the code and kept in perfect sync with the requirements.