The Agile Manifesto: Ten Years on (A critics view)

The agile manifesto has been around for coming up to 11 years. Most of the time proponents of agile methods always espouse its capabilities and why people should value agile people over process and always hark back to the 12 principles that underpin the agile manifesto.

However, through some of the interactions I had with one or two of the founders of said manifesto back in 2002/3, the leading agile method at the time (eXtreme Programming) was often compared to waterfall like method or other processes and the reasons given for their deficiencies were normally viewed through failures I the development process, when it was often the case that it was the failure to implement them correctly that caused issues.

Additionally, after working for a few companies which have used agile methods quite extensively and rigorously, I have come to notice a number of problems with some of the agile philosophy and indeed the way some of the more ‘formal’ agile approaches also exhibit some of the very same deficiencies that agile filibusters accused the more process oriented sectors of the industry of being (note, by ‘formal’, I mean those agile methods which have defined methods associated with them. Note, even XP had a method, as simple as it was, ‘User story->Test first->Develop…’)

Now, this is not meant as a blasting of agile methods. Agile methods have brought more structured ‘methods’ to an industry which has traditionally shunned any attempts to introduce engineering rigor. It is as if agile methods allow a ‘bridge’ into a world most so called developers find is usually above their heads. Plus, some of the concrete tools and techniques made famous by agile methods are good regardless of methodology (automated unit testing, continuous builds and deployment, QA processes and the like). However, there are a number of problems which have come about and I shall cite these in the 12 principles:

1. Satisfy the customer by rapid delivery of useful software.

This one is OK as a principle. It tends to lend itself to proto-typing methods with refinement (such as the ‘walking skeleton’ approach that some developers advocate). However, as has been found in other RAD methods, the customer will often want the prototype, resulting in code that was never production ready seeping into the codebase which will need refactoring later on as a technical debt exercise. Often, this tech debt is never repaid and if it affects the software architecture of an organisation, then there are problems, as other systems will couple themselves to that set of inadequate interfaces, requiring greater work later on.

2. Welcome changing requirements, even late in development.

This one is more of an issue. Being facetious, you can’t develop functionality in zero time, however agile you are. Indeed, the idea of ‘failing fast and early’ is completely counter to this point, as if an unforeseen failure causes a change in requirements is noted earlier, the extra time that comes about by gaining this ‘derived requirement’ earlier in the process is designed to mitigate risk. So I still maintain the longer it takes some requirements to come about, the less welcome it is.

3. Working software is delivered frequently (weeks rather than months)

This one is a holy grail, so I have no issue with it at all, as long as the quality is maintained throughout the process. If quality fails, the whole software becomes inadequate given often unseen or otherwise unknown requirements to the business (a technical debt repayment exercise that other steps may have introduced, is a prime example)

4. Working software is the principal measure of progress

From a business value standpoint, this is correct. However, putting my architecture hat on for a second (a hat that some XP exponents believe shouldn’t exist in the development process), the phrase ‘working software’ states nothing about ‘quality software’. So this often introduces inefficient software systems from a non-functional requirement standpoint.

Basically, all the quality metrics surrounding real enterprise and large scale systems are shunned for the preferred end-goal of addressing current functional requirements alone. QA and performance testing is a relatively recent adoption into agile developments (when it has existed in other methods for decades). As a result, elements of performance, security, maintainability and the like are almost never addressed in older agile minds. This has bedded in as a preferred method of working in most companies, as this is the way developers (who are really just programmers) like to work. Cut code that does something. The industry is pre-disposed to preferring this method as it is the principle they already hold and is the path of least resistance.

For some examples, imagine going to your bank ATM, knowing you can always withdraw money from your account because it works, but also knowing that the non-functional requirement of security is not high and everyone else can withdraw money from your bank account too. Not exactly confidence building.

Using an example closer to developers’ homes, if you develop highly coupled point to point enterprise systems and your tech debt is the refactoring and the refactoring is never done because you are only to deliver working software, then the coupling to other systems may explode exponentially, meaning addressing that technical debt becomes exponentially more costly and time consuming (especially when the interfaces for these connected elements are all different).

5. Sustainable development, able to maintain a constant pace

This is an ideal principle in heavier engineering methods anyway, so no arguments here. It allows for predictable timings for people who have to report and plan developments in the business. It is also particularly well suited to having Kanban and lean processes applied to it and optimising using those tools. So no arguments :-)

6. Close, daily co-operation between business people and developers

I like the idea in theory. However, this one is often even more idealistic than the agile proponents’ accusation that business people don’t read specifications and documents in heavyweight methods. In reality, companies can’t afford to hand over staff or there are political reasons why it can’t happen. Without a document for these decisions, agile methods can’t work at all.

Consider an organisation who buys into the agile process. They instruct the manager of a department to send a representative stakeholder to the agile team to sit with them for at least half a day every day. The wages of this individual are being paid out of the business budget and not IT. Whilst they are with IT, they lose the business department 4 or 5 times their salary in work (ether by loss of revenue or the combination of temporary cover, overtime and loss of productivity).

IT may also be paid out of the business budget (where cross invoicing occurs) and so the department are paying for their system and losing the revenue generated by that individual. This can be a process which sees departments lose so much that recouping the cost of the system would be difficult in the short term, agile or not and that is compounded by non-committal methods of agile development. It could be cheaper to pay for the overtime of the individual, get the individual trained in how to understand and write success criteria and have them send a story document, with success criteria that has been reviewed back to the IT team.

This one, in some companies, is a huge time-bomb waiting to happen. The only thing that has saved such methods in such organisations, is that no one has actually noticed that the cost to their department of £10,000 in wages paid, £40,000 of no revenue generated by that employee, plus the cost of the system on a cross departmental charge of, say, £50,000 far outweighs the £60,000 saving that the department will recoup on the existing setup.

Invoices such as the ones presented in department-department charging only show the cost of the development work, not the lost cost of the employee being relocated to the IT department (that is not a development departmental concern, so why would it appear on the invoice). This information is not immediately available and can sometimes only manifest itself in the departmental accounts sometime in the future.

A savvy business manager will figure this out. As a result, will they send a supervisory/managerial level employee if their department is fully utilised? I doubt it. They will send an underling, given them a responsible role and ship the closer to minimum wage employee to the IT department for the duration. It has the benefits to the business of:

• It costs the department little
• Their loss of the employee for a while doesn’t have a knock on effect on a large amount of other employees (contrast this with sending a manager)
• They see it as providing the best knowledge from the individual who is closest to the system

All this may increase the value for money that the business department can provide in the eyes of the departmental manager. The only issue is this may be interpreted as not being ‘bought in’ to the idea of agile development.

7. Face-to-face conversation is the best form of communication (co-location)

This is a doosie! Mainly because it is categorically false depending on your definition. There is no psychological basis to this at all. I have a few friends who are in the field of psychology and the figures for written and aural/oral communication are abysmal. It averages out at between 5 and 10% of what you read being accurately portrayed and you remember about 10% of what you hear. So you can see there is not much in it at all.

The benefit of the written communication however, especially if you pull in elements from NLP, is that if you can present the deliverable documents in the format most suited to the mindset of the intended recipients, then you have a consistent document, that a stakeholder (which includes a developer) understands fully, can refer to time and time again and get the same consistent answer. If someone has a conversation with someone else, something might be missed (especially if it is not first-hand), the quality of communication is generally very low and more often than not, highly inconsistent.

For an example of miscommunication, consider saying the word ‘services’. What do the following people think?

• Software developer
• Enterprise Architect
• Bank Manager
• Regional Manager of a car repair chain
• Hotel Manager
• Restaurant Manager

More and more modern methods out there acknowledge the importance of documenting the domain specific knowledge and terms in some glossary. So much so methods all the way up to TOGAF have formally included requirements for these business specific definitions in their standards. So even with the advent of agile methods, I am very glad to say that other areas of the field still maintain the use of a lot of the necessary documents.

This is categorically the worst manifesto principle. Writing documents last is fine for the development team (and they don’t want to write it anyway), but is no use if that document set is needed by two separate teams (such as how architectural work is delivered).

Also, I don’t see the sense in say, two teams developing code, then refactoring it and writing up their documentation (which never happens in practise) only to realise they have the same structures in it. That is a waste of development effort and run completely contrary to the lean principles modern agilists espouse.

Additionally, what happens if a developer leaves? This has two problems.

• The first is the loss of that tribal knowledge in the developers head
• The second, is that even if the knowledge is not lost, it requires a transfer to the new individual. If this means another developer sitting down with them and transferring that tribal knowledge, then this loses the seasoned developer’s productivity for that time.

If a diagram, which taken an hour to draw can save you 20 hours of refactoring, plus it mitigates against the risk of someone leaving, then I can’t justify the reliance on refactoring work and knowledge transfer, sorry.

Additionally, how many developers go to talk to the CIO directly and explain the project to them in terms they understand? Sometimes such communications can't happen, so a series of intermediaries need to summarise relay that information 'upwards'.

8. Projects are built around motivated individuals, who should be trusted

In an ideal world yes, people should enjoy what they do and desire to do a good job.

However, in reality, there are a few things wrong with this. This includes that developers don’t know every skill! Also, they may not have domain knowledge and trusting the team to be able to do a good job is impossible if they are not, say, mathematically minded when working for a finance organisation (you won’t believe the numbers on that one, much to my dismay), or have no idea how to optimise code/database queries.

I tend to sometimes chuckle to myself about the irony of developers ‘who should be trusted’, then getting told to do agile methods because they don’t trust that developers can produce good code by themselves.

9. Continuous attention to technical excellence and good design

You can’t do design! That is documenting up front :-D

Joking aside (because you have whiteboards and cameras don’t you?), technical excellence takes many forms and is not just limited to cutting code.

However, becoming ‘technically excellent’ in one domain often means you cannot transfer into another domain without a significant amount of effort. A more generalist approach would help with that transition, especially if the organisation is struggling to recruit into particular roles. The supply-demand curves for devs, QAs and BAs is never the same in the industry all the time every time. Having a more generalist approach allows for an appreciation of the other roles in the team (which fosters better communication) and allows the vacancies to be filled easier when supply is higher in one domain than another. I can certainly advocate ‘Role based’ responsibilities being fostered, but detailed, specialist jobs I have a problem with from both a recruitment and intra-communication perspective.

Now, I appreciate the agile manifesto says nothing about the above. However, I have met some people who take the above to mean that people will become excellent and dedicated to their sub-field alone, which is fine, but the worry is that they become so specialist, that the ability to bridge the communication gap to their team-mates is severely diminished and given we have no documents, quality of development dynamics will suffer.

10. Simplicity

I don’t have a problem with this in theory. I have a problem with the way it has been applied in industry.

Simplicity often gets tagged by the KISS principle (Keep It Simple Stupid). However, there is a much better rule used in almost every other engineering discipline and that is Occam’s Razor.

Basically it infers “All things being equal, pick the simplest thing that works”

Pay particular attention to the words at the beginning of that statement, “All things being equal” and let’s take a look at a classic example you can probably remember from various courses you may have done over the years (especially in higher education), the requirement to sort a list of items using bubble-sort and quicksort.

Functionally, both bubble and quicksort will sort numbers into the right order. So they are both equal in that respect. KISSers will then state “OK, I am going to use bubble-sort”.

So they make it happen. The list then eventually contains over 1,000 items. It slows to a crawl! They then have to revisit this decision, identify new options and re-implement the solution, yielding more waste. Why was that? [rhetorical question].

A RAZORite will have asked questions such as:

• What is the algorithmic complexity of each solution?
• How many exchanges do I need to do?
• How much memory is available to me?
• How well will this scale when more items are added?
• What is the performance profile of this algorithm?

When they have found that all things were NOT actually equal, they would have chosen an appropriate solution out of the sorting repertoire immediately. It is the old trade-off analysis again.

In general, I have never seen an agile method deliver well optimised, performant code first time or even explicitly consider it in any part of the initial design. Fast teams do no thinking (and Katas etc. foster that mind-set, encouraging the developer into autopilot) and scoff at attempts to get them to do so. I tend to safely story my ‘I told you so!’ cards for such occasions when the non-functional requirements have not been implemented or thought about from the offset (authentication and authorization being a prime example).

11. Self-organizing teams

This is fine. No autocratic dictate of who should do what when. The team decides its own protocol.

The difficulty comes when you scale it upwards. The bigger the team, the less organised it becomes. Also, in order to foster increasing levels of self-organisation, the team have to develop the foundations to support agility in ever increasing teams. This means some of the foundations will have to be set and this can include documentation, metrics, Kanban strategy and the like.

However, in reality, teams stick too rigidly to the mistaken belief that agile methods mean none of that. The manifesto only specified there is a ‘preference’ for one thing over another. The misinterpretation of this as ‘don’t document’, when it actually says “working software over comprehensive documentation” (Which I joke is how it is read by KISSers and not RAZORites, see above ;-) tends to mean agile teams lose the knowledge needed to be communicated (intra or inter-team) either over time or through too quick a team change.

In order to facilitate team decision making, metrics are an important part of the toolkit. Just like a CEO needs the business intelligence to support their decision making, an agile team need the metrics to be able to plan, optimise and ultimately, become predictable.

I remember sending an e-mail to someone at a client of mine stating that there should already have been a collection of some metrics (story points) and that they had a calendar of events that happened (including things like holidays, staff leave, high priority ‘red flag’ issues etc.) and they should correlate these events to the effects they had on the metrics. This can been done by using a Taguchi methods or statistical factor analysis to find the actual relevant variables affecting the velocity. This is a standard method in quality engineering in manufacturing industries and seeing that Kanban is routed there too, it is a natural transition to accept this in the software world.

12. Regular adaptation to changing circumstances

This is good. I don’t mind it within projects at all and it is a holy grail.

However, if an organisation is shifting priorities, then the decisions on delivery of software is somewhat taken out of the hands of the developers. Note, they will always be delivering software, it is continuous integration after all, but if the software is not complete to deliver the value at every stage, for example, delivering a story as a release or iteration, which only covers 60% of the value in the prioritised release backlog, which doesn’t deliver the total (or even sufficient) business value before losing business priority to a much more important project, such as a change in the regulatory landscape (which requires prompt action), then as well as delivering a value only equivalent to what has been realised so far, if the project is a migration one, you may have part migrated the project, resulting in a split of functional concerns at an architectural level.

It is often hard to find that magical 80% point suggested by Pareto’s in some projects and even harder to implement them in an every changing landscape if you don’t have tools and techniques to support it and metrics are a vital way of doing that.

From an agile perspective, a technical debt exercise of that magnitude is incredible difficult to put right later if other systems have come into play on those connectors separately later on. Trying to fish out the new systems tacked on to old ones and the others which were tacked on to the new is a difficult exercise, that costs more at the time that you do it (because there is more in place to fish out). It requires governance which is somewhat at a tangent with agile philosophy (people have to be trusted and people over documentation) or at best, is at a much higher organisational level.

Summary

Agile methods work best in environments where there used to be chaos. Where established structured method exist and work for the organisation, purely agile methods are a retrograde step. However, in reality, there is very little in the way of adequate structured methods in organisations.

Through time, we have seen agile methods meshed with other methods (‘agile’-‘waterfall’-‘agile’), placed as part of a bigger strategy (such as TOGAF-Agile) or agile teams seamed together (Scrum-of-Scrums). I note that Agile is never compared to RUP directly, which delivers value in the form of use cases or groups of use cases in iterative cycles. Anyway, these seem to be the small steps that are needed on the journey to becoming agile and indeed, some organisations choose to stay in some of those intermediate states.

Agile methods are not scientifically proven. I still maintain that it predisposes itself to developers who are really just programmers, but again, this is not always a bad thing. Indeed, that vast majority, some 80% to 90% of industrial developers here in the UK are not engineers, nor have they an engineering mind-set. It is all about the functional elements of the code within the component boundary. Architecture is not their concern, and non-functional requirements they consider secondary. So to introduce some quality in the functional aspects, where previously there was none is a good thing. But it is certainly not a catch all and should not be a total substitute for a working structured practise in isolation, at least immediately.

Mistaken Myths: Number 2. You can document in agile methods once the software is done

This is a classic and a fairly easy one to dismiss.

In my younger IT days, late 2001 to early 2002, when Agile methods started to come to the fore in the UK job market, there was quite the fanfare from the people that used them. Talking specifically about XP, I remember e-mail discussions with one of the founders Ron Jeffries. The XP proponents around me in the company I was contracted to, claimed you never wrote documentation. Coming from a background where documentation was a key deliverable for transition at lots of stages in any 'heavyweight' process (RUP/Waterfall), I could not see how adequate communication from one stage to the next could take place without everyone being on the same page.

I didn?t know a great deal about agile methods at the time, so I ended up having to get in contact with the XP brigade and it was Ron who replied. I communicated my concerns about this to him, but he replied that it wasn't that you didn't write any technical documents, just that you would write them at the end of the deliverable of the story or release (aka in sprints and releases these days). That way you know what you have delivered and the document is as up-to-date as it can be. I will paraphrase what I remember he said, but apologies to Ron if I have incorrectly recalled the events of 10 years ago.

He cited reasons that included:

1. Nobody reads documents. Clients don't read them and developers certainly don't read them.


2. Nobody updates documents. They have a nasty habit of being written once, something changes and the document becomes obsolete.


3. During a development phase, requirements are not immutable. So changes to the model may need to be made on the fly. If you have to change a diagram on a static document before you start to write your code, then given no-one will read it, you are wasting time writing a redundant deliverable from the perspective of delivering code.


4. The tests should be your documentation.


5. From the code, it should be self-evident what the code is meant to do, as that is the final arbiter. In other words, the code should be your documentation.
   Before I comment on this, I have to say that it was a decade ago. Ron is a capable professional and whilst our e-mail exchanges back then saw us pretty much at philosophical loggerheads, there are elements of his philosophy and those of agile methods in general that have brought nothing but good to the industry in that time.
   However, as with all agile processes, it is the people that make it happen. If you can't get the people, the company culture is against it and the business doesn't have buy in, then it is destined to fail and you will come up against an immutable wall of a different kind.

In the UK, many organisations fail to implement agile methods properly and pay the Cobb's Paradox price as a result. I will hopefully come to what I see as some of those reasons in a later blog, but to concentrate on the above, we just need to mention that, certainly in UK IT, people HATE documenting with a passion. Also, most hate writing unit tests first or carrying out spikes, but that is another story. It is regarded as overly bureaucratic. The majority of industry developers want to hack around with deliverable code in a wholly amateurish way and quite a lot of organisations out there simply let them do it. So when someone comes along and says "You don't have to write anything until the end, but it will improve code quality", they are predisposed to read this as "You don't have to write up anything and you become better" and any method advocating this gains a lot of traction very quickly.

In the early days of agile adoption, a customer's resource had to be available on site to sit with you whilst you went through the story and coded the corresponding result. In the UK, given the amount of free time nobody has, this was always going to be an impossibility for most organisations. So you would often get an electronic paper tennis game leading back and forth to customers who didn't have time to come into the software house to deal with things.

This would often happen with one developer as contact, who like all developers of the day, kept him-or-herself and his-or-her e-mail in his-or-her silo and the e-mails never came to the fore. The decisions should have been picked up by their pair programming buddy, but if he-or-she didn't know the conversation had taken place (having been on leave for a couple of days and the first programmer pairing with someone else), it wouldn't cross their mind. The programmer that received the decision should have put it somewhere for traceability and written it up, but they could cite "You don't have to write any documentation" and a period of time later, they would complain to the IT manager in a panic when the e-mail sweeper auto-deleted their e-mail, hours before the critical moment the big boss was asking in an enraged voice "who told you to do that?"

In any case, it was never brought to review, so knowing how well whatever was done couldn't happen due to the lack of traceability. At the time, sprint backlogs and Kanban didn't have the prominence they have now.

A much bigger issue that is still around today is what happens when all this tribal memory and wiped down whiteboard work floating around in peoples' heads decides to leave before it is written up? A previous client once had a number of cynical developers leave in a very short space of time to disparate organisations which offered better pay and no unit-testing or development rigor. Them leaving caused a resulting melee and manifesting chaos as people had to pick up code they knew nothing about and run with it. The handovers were not sufficient, process and policy documents were not readily available, there were certainly no specificaition, the unit tests had little coverage (so there was no confidence in them), the code didn't have comments (which was one of the enforcements of agile processes that those particular developers loved) and there were absolutely no traces of documents or e-mail trails as the e-mails were lost when the accounts were eventually purged.

This is easily my biggest gripe about agile philosophies that advocate no up-front documents. Everything is stored in tribal memory and that information gets disseminated in the dynamics of organisational culture. Everything has to be in place for that dissemination to take place. This sort of dissemination is very delicate, as even the placement of walls in a building can stop the inter-cultural flow of memes.

To characterise this, one team learns something new, places it on their project portal (probably via an electronic document ;-), but with no link to the project portal from any other SharePoint site say, or development wiki, nobody ever sees it. As a result, time passes, other developers spend their time re-exploring that wheel not knowing that others in the company have done this work already, wasting another x amount of time wheel-inventing. This can happen four or five time and if key people leave in the meantime, you not only lose the information about the role, you may also lose the fact that you learned that lesson before. So the organisation is not learning. Drawing analogies with the human brain, it is like losing the brain-cell just before it has even started to make the connection to others.

Personally, I think there are some very easy solutions to the problems highlighted by Ron above. However, they are seemingly incongruent with the views of some misguided agile proponents. Ironically, a lot of these were conceptually presented as part of the CASE and MDD/MDA schools of thought decades ago, but a certain 'biggest' name industry leader has only just caught on ;-)

So some of my solutions to the above are:

1. Keep the documents concise, but get them done! - If you have to present requirements to clarify the project backlog elements, then do so by presenting a list of them with a click through to the full page detailing the deliverable citing success criteria, the stakeholder, the description etc. This can be in the form of a SharePoint list linked to the actual parent work item in TFS. Customise if you have to. The amount of time this will save the organisation you would not believe!


2. In Windows, use OLE to link to Visio documents - At this moment, standard VS2010 class diagrams cannot adequately be OLE linked to Word documents, but Visio will do the job nicely. I have created a screencast and posted it below to show how this can be done. When used to link documents, this gets around the problem of the document becoming obsolete if the only the model is kept up-to-date.

   
   
   

   
   




3. Take a long hard look at customer approval processes - The excuse that nobody reads the documents is true, but it won't be solved with, say, having the customer in the room without resistance and to some degree, I agree with them. I will come to the financial reasons for this in another blog, as that is a doozy!


4. Make sure your tests are complete and consistent! - In agile methods with no tested designs (usually presented in documents), more than any other class of methodology, this becomes the biggest single point of failure that can exist in the SDLC. If your tests are incomplete, inconsistent or just plain wrong, then you are risking the entire project, because you cannot validate the design and code at any point. You must know how many tests you will need! QA members should come down hard on developers who miss this. We have failed to self-regulate in the development world, so it is time to play the ?self-regulate or legislate? card.


5. If nobody reads documents, information will be lost - There are two parts to communication in general, there is that someone transmits a message and someone receives it. Without both those actors in the system, no communication has taken place?. Ooh! I hear a tree falling in a wood!... The communication is almost never a 60?s Chomskian ideal, but at the same time, the amount of beneficial lessening of ambiguity, and decision traceability that up-to-date documents give anyway, cannot be substituted if a project manager has to get and install a license of VS2010 to get the code and run a badly ordered set of the test, with no comments to see what the system does. A set of TFS burn down charts, test profilers, build failure WebParts are a useful statistical toolset, don?t get me wrong, but it compares the code against, say, tests, test coverage, developer work rates but you can?t guarantee the tests are correct from the specifications. Additionally, the information about why they came about (and the business criteria they are testing) can be been lost if a badly written work item is put in initially. TFS gives you the tools to do it properly, but unfortunately, almost no organisation that I have worked in recently does.


6. Relate meaningful method names, properties, constants, fields and variables to the Business Domain Specific Language - This should be standard practise. It is not enough to use some of these domain specific names without a glossary or definition reference (which is a document). The business knows what these terms mean. As developers, we almost never know what the business means. So it is important to use the DSL of the business and this involves learning what those meanings are. Then once members of the organisation learn something and document it, the rest of the organisation can pick that up and run with it. It is part of a microclimate of internet blogging and group consultation (in the form of dojos and group katas). For blogging, SharePoint gives you that ability, so use it.

Given all this, and more, it cannot be understated that iteration zero is very important! Those foundations will set you up for the entire project?s success or failure, so GET THEM RIGHT!!

The underlying theme in a lot of this is that all that has happened in the decade or so since XP took prominence is that our definition of a document has changed. We have not eradicated them (or even the paper that comes with the, that was donated by the falling trees), far from it. Correctly applied documents have embedded themselves in the best development cultures but the just have stopped being called specifications.

The thing is none of this is new. These are lessons that were learned 20 or 30 years ago, but this time, the people have a greater proportion of the responsibility (but often don?t know it). So you have to get the right people.

Even though I prefer heavyweight approaches, I still see the immense value good, solid, QA; automated unit testing; automated builds; continuous integration; knowledge sharing via dojos etc. have as individual elements that can be applied to heavier methods. Indeed, since coming across the automated xUnit philosophy in 2001, I had used DUnit in every system that I developed in the interim before before shifting to .NET and picking up the VS suite. This is a must as far as companies are concerned. Good quality unit tests as good as guarantee the quality of the testing is solid, as it is repeatable and can isolate individual areas of the problem space to look at should something go wrong. But this doesn?t detract from the fact that if test are wrong, without traceable documents, you have no idea if it is the test that is wrong, the code that is wrong, if someone misinterpreted an ambiguous statement from the client, or the client didn?t understand the question. It is the glue between these different flowing elements of the Kanban board and without them, we cannot validate or verify anything.

Mistaken Myths: Number 1. Your code should be self documenting

This is a fairly classic misunderstanding, yet one that is spouted a lot in the industry.

It seems pervasive that developers shoud produce self describing/documenting code. To a degree, I agree with this, but my viewpoint is that comments in code should lead to WHY something is being done and not reference how. More a specification of the method than how it does what it does without understanding what the start and end goals are (success criteria if you want to put it in TDD terms). This is a view shared by a few member of the industry such as those following in the footsteps of "The Pragmatic Programmer" and not always those only blindly following what I keep getting told "Code Complete" recommends (Note, I have not read the book myself, so can't comment on if it is the book that actually recomemnds this, or the person reading the book that does :-)

Decision traceability is something that is almost impossible to get from code alone. So some adjunct mechanism is often used, like referencing JAD/JRP sessions, original work requests/bug reports/version control logs in larger organisations, or simply a log book/notepad in smaller ones. Some developers choose to comment their code, but the comments have to be good quality. A comment that is not updated has the same productivity loss as the loss of 'tribal memory' (as Grady Booch often puts it) regarding an application (Which I will get to in a later post), so the comments should be treated with the same respect as actual code, especially if you are generating documentation from it.

In other engineering disciplines, most decisions are given a reference code and slapped on design diagrams and documents. This allows the tracing of the decision all the way back to the original discussion that led to those decisions being made. In software development, this has started to finally get through to some groups.

Additionally, I prefer to place the functional specification (I write them in OCL, given I have a bit of VDM in my history :) in the form of pre and post conditions at the top of the method/function. It would look something like:


/*
* --- ref: RQ/SH01/01 ---
* context AccountingServices::TryConnect( Host : Uri,
* Port : Integer ): boolean
* ------
* pre: registeredAddresses->contains( Host )
* post: ( result and AccountingServices.Host.Connected ) or
* not( result or AccountingServices.Host.Connected )
*/
/// <summary>
/// This method attempts to contact the host server and establishes a
/// connection if an address is one of the registered addresses.
/// <example>
/// ...
/// if ( AccountingServices.TryConnect( hostAddress, portNumber ) )
/// ... Do Something ...
/// else
/// ... Do Something else ...
/// ...
/// </example>
/// <param name="HostAddress">The host location to attempt the
/// connection to</param>
/// <param name="port">The port number to connect to</param>
/// </summary>
public bool TryConnect( Uri HostAddress, int port ){...}


Or you could just apply the reference and hope that a developer will read the documentation...

...ooh look over there! A rainbow, I need to catch it!! :o)

But before I go colour hunting, good quality comments are a good thing. Donald Knuth's Literate programming, despite his best efforts between the 1970's and 1990's, in its entirity, has been consigned to faded memory in modern day imperative paradigms. Though the principles it pushed live on in the new guise of documentation comments (such as those for JavaDoc, DelphiDoc, DOxygen and SandCastle).

The problem is using these tools under time pressure. Documenting code is often relagated to third class status, way behind getting code out of the door and unit testing. It is performed with the mentality that 'I will do it tomorrow'.

Sometimes it is up the QA members of the team to demand that this be done, especially when no formal design documents have been created and the whiteboard has been wiped clean...

...Oooooh!! It's getting away...

..Otherwise it is lost when that 'tribal memory' fades or joins another 'tribe' :o) As the best efforts of the developers in writing unit tests, using good method and variable names will never explain what decision was taken and why.

Some developers and companies regard good documenting comments as 'Gold Plating' and in doing so, will end up paying for the time of a comparatively highly paid contractor/consultant to repeatedly chase up the source of the decisions when the decision makers may have done an Elvis and left the building. If in the end the 'tribal leader' who mde the decision isn't based in the organisation any more, you are pretty much stuffed. So this highly paid consultant will trawl through tens or hundreds of thousands of lines of tests and code, not knowing if either accurately reflect the businesss process and if they are new, not even knowing what the business process is in any meaningful detail, for days or weeks at a time making zero progress on development or bug fixes before (s)he finds the source of the problem and a ten minute job later, it's fixed!! Well done! Waste Maker Corp, with your misinterpretation of lean principles, you have just wasted thousands (or tens thereof) of your own company's money because you didn't let a cheaper developer spend a couple of hours putting documenting comments in.

...crap, the rainbow's gone!! :-(

Not to worry, there will be other rainy days.