Skip to main content

Design is Important

When I was a student I used to cheat. Not in exams or practical assignments, but I used to cheat when it came to my process to develop code. Early on I noticed a common pattern. After receiving an assignment I would perform some analysis, figure out a basic design and document my steps. The problem came when to code up the solution. I may have overlooked something, or made a mistake. Sometimes I would just come up with a better solution. This meant any time I spent documenting was lost. It turns out this wasn't cheating, after all there was nothing within the assignments enforcing a waterfall approach.

I wasn't alone with this experience. Most of my peers had the same issue, and the report aspects of an assignment were often disliked for this very reason. My solution was simple. Code up something, get it working then document the design aspect. Rinse and repeat. Back in the early 2004 I wasn't aware of agile methodologies, but this solution worked a treat. In turn my classmates started to adopt this similar approach, either from my encouragement or their own discovery.

Moving from university into a practical environment was a joy. It almost appeared as if little to no documentation was produced. The documentation that was produced, was often created by other teams. Developers simply wrote code. At the time I thought this was great, but after some reflection the errors of my ways have been highlighted.


In my experience a variety anti patterns are to blame.

  • No or limited design

    The worst thing that can be done when it comes to design or planning is the absence of any design or plan whatsoever.

  • Coding your way out of problems

    Given some limited or poor design, I've often experienced scenarios where 80% of the tasks will be complete, then you hit a roadblock. In order to progress the team will hack their way around it, introduce technical debt or put in some not so temporary fixes.

  • "Weeks of coding can save hours of planning"

    A colleague I used to work with used this once and I fell in love with the quote. Take an average web application, if the life cycle of this would be a meager two years, spending a few hours putting a design together is nothing. You could argue that spending a few days would be equally fitting, better yet a couple of weeks well thought out design is only a small percentage of the overall cost of delivery. When it's too late you can code your way around the problem. Though this debt will soon add up, meaning features are even slower to add going forwards.

  • Playing the "Agile" card

    A misconception of the agile manifesto is to favour "working software over comprehensive documentation". Most developers read this as never document anything. This is far from the truth. Documentation, design and planning should be built into the product in iteration. Just In Time (JIT), rather than all up front or never at all.

  • Greenfield projects

    Having been involved with a couple of "rewrites" I've seen this happen first hand. No design, limited design or bad planning in the first few iterations of a project can kill it. Only by iteration three, four or five will you notice something isn't right. At this point you've lost. Suggesting to restart, reboot or refactor is a hard sell, especially to management teams. Architectural changes are very difficult at this point, as you'll most likely have users, automated tests and other teams relying on what you have produced.

  • Refactoring can save the day!

    Give me a bad class or method and I can make it beautiful. Give me a bad application and we have a problem. Refactoring is a class or method based activity. I don't buy architectural refactoring - and I'm not alone. Emergent design is a very powerful tool, but without some upfront planning you'll be stuck in limbo.


There are a few ways to overcome the previous problems.

  • Whiteboards

    As much as I love technology you cannot beat a whiteboard (or piece of paper) and a couple of engineers. Visual collaboration in this manner is very easy, plus physically having the presence of another individual helps. You can also snap a picture of these diagrams to reproduce them in a more friendly, shareable, digital form afterwards.

  • CRC's

    Class Responsibility and Collaboration cards are another low tech solution, but one I find incredibly valuable, yet for some reason don't appear to do enough of. Best performed in groups, though I've had some success on solo efforts.

  • JIT documentation

    Not pages of wiki articles or documents, just lean, self contained documents that serve a purpose. Develop these in iteration and you'll avoid a "documentation sprint" from hell.

  • Code itself

    Prototypes are worth their weight in gold. Spike solutions when used across a team are also incredibly effective. Rather than a single prototype being produced, each team has a crack at the problem in isolation. After regrouping you present back your solution and findings. The team then combine to form a "best of breed" approach.

    Iteration zero is often used for getting the build up and running. If you take this one step further, the ideal scenario is to produce a walking skeleton. This should consist of empty or basic class/method/function definitons that have not yet been implemented. With a basic API in place, fleshing out the details is rather enjoyable. You focus on the problem, not the design or architecture.

None of these are ground breaking ideas, but combined these approaches have served me well both personally and professionally.


Popular posts from this blog

Three Steps to Code Quality via TDD

Common complaints and problems that I've both encountered and hear other developers raise when it comes to the practice of Test Driven Development are: Impossible to refactor without all the tests breakingMinor changes require hours of changes to test codeTest setup is huge, slow to write and difficult to understandThe use of test doubles (mocks, stubs and fakes is confusing)Over the next three posts I will demonstrate three easy steps that can resolve the problems above. In turn this will allow developers to gain one of the benefits that TDD promises - the ability to refactor your code mercifully in order to improve code quality.StepsStop Making Everything PublicLimit the Amount of Dependencies you Use A Unit is Not Always a Method or ClassCode quality is a tricky subject and highly subjective, however if you follow the three guidelines above you should have the ability to radically change implementation details and therefore improve code quality when needed.

DRY vs DAMP in Tests

In the previous post I mentioned that duplication in tests is not always bad. Sometimes duplication becomes a problem. Tests can become large or virtually identically excluding a few lines. Changes to these tests can take a while and increase the maintenance overhead. At this point, DRY violations need to be resolved.SolutionsTest HelpersA common solution is to extract common functionality into setup methods or other helper utilities. While this will remove and reduce duplication this can make tests a bit harder to read as the test is now split amongst unrelated components. There is a limit to how useful such extractions can help as each test may need to do something slightly differently.DAMP - Descriptive and Meaningful PhrasesDescriptive and Meaningful Phrases is the alter ego of DRY. DAMP tests often use the builder pattern to construct the System Under Test. This allows calls to be chained in a fluent API style, similar to the Page Object Pattern. Internally the implementation wil…

Coding In the Real World

As a student when confronted with a problem, I would end up coding it and thinking - how do the professionals do this?For some reason I had the impression that once I entered the industry I would find enlightenment. Discovering the one true way to write high quality, professional code.It turns out that code in industry is not too far removed from the code I was writing back when I knew very little.Code in the real world can be:messy or cleanhard or easy to understandsimple or complexeasy or hard to changeor any combination of the aboveVery rarely will you be confronted with a problem that is difficult. Most challenges typically are formed around individuals and processes, rather than day to day coding. Years later I finally have the answer. Code in the real world is not that much different to code we were all writing when we first started out.If I could offer myself some advice back in those early days it would be to follow KISS, YAGNI and DRY religiously. The rest will fall into plac…

Feature Toggles

I'm a fan of regular releasing. My background and experience leads me to release as regularly as possible. There are numerous benefits to regular releases; limited risk, slicker release processes and the ability to change as requirements evolve.The problem with this concept is how can you release when features are not functionally complete?SolutionIf there is still work in progress, one solution to allow frequent releases is to use feature toggles. Feature toggles are simple conditional statements that are either enabled or disabled based on some condition.This simple example shows a feature toggle for an "Edit User" feature. If the boolean condition is false, then we only show the "New User" feature and the "Admin" feature. This boolean value will be provided by various means, usually a configuration file. This means at certain points we can change this value in order to demonstrate the "Edit User" functionality. Our demo environment could …

Reused Abstraction Principle

This is the second part of my series on abstractions.Part 1 - AbstractionsPart 3 - Dependency Elimination PrincipleThe Reused Abstraction Principle is a simple in concept in practice, but oddly rarely followed in typical enterprise development. I myself have been incredibly guilty of this in the past.Most code bases have a 1:1 mapping of interfaces to implementations. Usually this is the sign of TDD or automated testing being applied badly. The majority of these interfaces are wrong. 1:1 mappings between interfaces and implementations is a code smell.Such situations are usually the result of extracting an interface from an implementation, rather than having the client drive behaviour.These interfaces are also often bad abstractions, known as "leaky abstractions". As I've discussed previously, these abstractions tend to offer nothing more than simple indirection.ExampleApply the "rule of three". If there is only ever one implementation, then you don't need …