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.

What if everybody is wrong? Well, not everybody, but majority.

Reading Kelly Water’s Post about “Agile Project Management: Avoiding The Waterfall” I came to think about this. Almost nobody claims today that they are following waterfall, because of the very bad connotation that word now has, but not actually because they understand what are they doing. Same thing for Agile followers.

From the post, I rescue that any process that has phases reassembles a waterfall. From actual presentations, blogs and discussions, Agile often means just following methodologies like Scrum, Lean or XP. Now I question: are we right about this? Let me see if we are, or not.

Waterfall is a term, it seems nobody knows who coined it, related to a phased methodology. Dr. Winston W. Royce wrote about it (without given that name), describing an ideal form that was not so good. The phases were the requirements gathering, analysis on those requirements, system design, coding, testing and operation. The ideal was each step may iteratively cycle with the next down and the next up, in little steps. The flaw was it was usually the case that testing will not just go back to coding, but it may go up till design, and from there, jump back to requirements gathering again. That flaw (the large back jump) was caused not because the phases, but because the testing phase is where the actual product is finally validated against design and requirements.

The problem is, there is no solution to this. We can dilute or minimize the impact of the testing findings, using several techniques, but we cannot avoid it. At any level, team or individual, the same steps are repeated: I see what it is needed, I analyze what is possible, I think on how to do it, I do it and finally I check if it works. That can describe the process of developer creating a simple three line method! That is, phased development is there, everywhere, and that is not the problem. The problem is when that phased process is done in a way that the impact of facing reality with needs is too big that multiplies the work and the cost of the back jump.

So, the waterfall illusion is when you think that rain is not a waterfall, simply because the raindrops are so tiny you don’t see them fall individually. But they fall anyway. It means, people that think eliminating the analysis and design steps and jump into coding breaks the phased process, I’m sorry, it doesn’t, it may avoid a large body of water fall into one place, but will make millions of little bodies fall everywhere. See the point?

Ok, there is another idea into this, and that is to make the water flow up. You start coding, with no idea of what you need, and then the phases are completed backwards. (Hey! If you want to start really backwards, then start by testing! Oh, yes, we have TDD). The code will make a design “emerge”. The next logical steps if to create requirements that match the design. Well, I guess that does not work. In that case, the requirements are still presented before coding. So the new phases are: requirements, coding, design, testing. Or, requirements, testing, coding, design, testing, coding, design, etc. Anyway, we always have phases.

Pages: 1 · 2 · 3