Agile taste for working code over documentation may be misleading to some. As seen in many posts and discussions, it seems that it means no documentation at all for some people. For another group, it means you just need to start coding, nothing else matters. This post is to differentiate plain coding from development, and to explain that working code is more that just executable sentences.

Let’s start by saying that code is the description of a solution in some sort of language. I defend the position that the description of a solution may not be executable. That description is to be read sometimes by the machine, some others by humans, and some others by both. The description has to have an abstraction level. That is, based on the approach we use to describe and to whom, it may be machine language (assembler for instance) or a high level code like a DSL. And we don’t just write ones and zeros because we will need later to revisit that code, and be able to read it and to make changes. Bear with that in mind for later.

Development is not just coding. It involves finding the why in the business needs and decisions, deciding the how we will solve that, actually describe the solution (to stakeholders and to the executers), and verify that solution meets the needs.

One point to clarify here is the executers concept. A solution is not a chunk of code. A solution may be a complex system, that is software intensive. That means it is not just code, it usually contains processes, people, and many other elements. All together are the solution. And that system is to be built in development, not just the code part.

There are several other tasks that should be performed during the development process. As we deal with humans, you need to have people management. A group has always issues, problems, questions. Also, humans need material to work with. Meetings, information, computers, and many other assets. During the development, several decisions should be made, and not just about code: deliverables, QA scheduling, assignments, feature modifications, priorities, etc.

People needs to communicate. Creation of communications channels, management of those, coordination, moderation, etc. Some voices say all that work should be done by developers themselves. Not so sure about that. Some other say that is not needed, we just need code writers to write code. Not sure that works either.

So, so far, I believe development is far more a complex process that just writing code. And coding is far more complex that just writing an executable set of instructions for a machine (Description of a solution, remember?) Thus, I proclaim that coding is not the same as developing. Let’s continue.

Going back to the coding definition. Some people think that a non executable code is waste. Specifically, design is seen as useless documentation, wasted time. Here then I start to defend what we may call design.

Non executable code is that one that describes de solution, but may not be read be a machine and may not be executed by it. As we mentioned before, the executer may not be a machine, but let’s assume the executable code is executed by a machine not to mess with concepts. Some of that code is the one generated as strategic and tactical description, aka, architectural description and design. If it is not executable, why do we need that kind of code? There are several reasons:
- The ones to design are the developers, why? Because it is a description of the solution, and thus code.
- Executable code is often done quicker when the ideas and major decisions are already made in the design.
- When code is done, it is usually reviewed and almost always changed to improve it. Describing at design level is quicker than writing low level code, and thus fixes and improvements can be made earlier, saving time and effort (changing executable code, large portions of it, may have a great cost and impact).
- Once done, the executable code should be verified. Checking against a high level description helps to verify. If it is different, then it means either the decision at high level or at low level need a review. It is important that both descriptions are kept in synch.
- Why doing the work twice? Because they are different works. Description at high level is used at some time, and the low level description later. But both are used. Missing one means there is something in development that may have more cost later. See next point.
- Development is never finished with complete code delivery. There are always enhancements, additions, changes. To decide why, how and what, it is always important to know what is done, how and why. Reading machine code means almost impossible changes. Reading executable code is possible, but at high cost. Reading a high level description, that was kept in synch, is great.
- Design is not a documentation process, it is a description process that should be used through the development. If design outcome is not used, the it is waste. Design that is done trying to be complete before operational coding, it will also be a waste of time. Design should be made in regular chunks, not to little ones that misses the tactical view, not so big so that you end up making decisions with not enough information.

So, given the ideas above, I want to proclaim that used design is actually working code, and thus, if well done, complies with Agile thinking.