re: Should Coding be Trivial? VIEW POST


I've not heard the interview with Leslie, but I suspect his point was that at a coding level, you often 'cannot see the wood for the trees' so your next goal (aka BDD test!) is unclear, and coding without a clear direction is frequently unrewarding for the people doing it and inefficient at producing output that is valuable to the stakeholders. Thus some design work must occur on a larger scale, what matters is the way that's done and how it supports the delivery process. IMO: this is where the Agile Manifesto & Lean engineering - both aiming to keep cycle times low and efficiency up, and design techniques such as domain driven design and evolutionary architecture - both aiming to reduce the amount of coupling and up front design work required, can really help.

I like the concept of 'just enough documentation', preferably in the form of testable statements (did I mention BDD?), supported by minimal architectural information (eg: in architecture decision records) and technology information (eg: language(s), tooling, dependencies, style guides, delivery workflow) that enable a team to get on with delivering a few clear outcomes at a time, reviewing regularly with stakeholders.


My point is not about requirements specification or high level design. These need to be documented, at least to a certain extent before coding starts. Especially if more than one person is working on the project and you have to assign tasks.

I do have an issue with lower level design outside code. To give an extreme example: I keep seeing people define function prototypes in Microsoft Word documents. I have even done that myself because I was supposed to write a detailed specification, so I tried to be as detailed as can be. This is something that,from my corrent point of view, makes no sense at all.


Ah ok, my apologies Frank, I dived in :)

I too would have a problem with things like function prototypes in static documents, that does seem excessive. I think design decisions, such as the particular patterns selected to address a challenge, are worth recording, along with the reasoning behind them. This could be in a block comment in the code, or maybe on a confluence page as a picture with some explanation. As you have noted, all of this non-code work is debt to be maintained, so worth reviewing it's value at appropriate points.

code of conduct - report abuse