DEV Community

Discussion on: Should Coding be Trivial?

Collapse
phlash909 profile image
Phil Ashby

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.

Collapse
fpuffer profile image
Frank Puffer Author • Edited on

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.

Collapse
phlash909 profile image
Phil Ashby

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.