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

Constant Object Anti Pattern

Most constants are used to remove magic numbers or variables that lack context. A classic example would be code littered with the number 7. What does this refer to exactly? If this was replaced with DaysInWeek or similar, much clarity is provided. You can determine that code performing offsets would be adding days, rather than a mysterious number seven.Sadly a common pattern which uses constants is the use of a single constant file or object. The beauty of constants is clarity, and the obvious fact such variables are fixed. When a constant container is used, constants are simply lumped together. These can grow in size and often become a dumping ground for all values within the application.A disadvantage of this pattern is the actual value is hidden. While a friendly variable name is great, there will come a time where you will want to know the actual value. This forces you to navigate, if only to peek at the value within the constant object. A solution is to simple perform a refactor …

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…