Some background

I am the newest member of a small team of 3 developers. For the past two years I have been working with them on an application the two of them made roughly 5-6 years ago. This application has no documentation and no design or analytical methodology has ever been applied to the development process. The latest medium-scale change to the system dragged on for over a year as a consequence of the convoluted mess that is our current codebase.

As a result of my post-mortem analysis on this change, we are moving towards a full rewrite of the whole application since the market is moving faster than we can extend the system. This time, however, I have urged that we do so methodologically, rather than rush forward. This was met with enthusiasm, though it has since become clear that my coworkers are not experienced in software design on any level.

To the question

I am the only person in my team with any experience in terms of software design, and that experience is purely academical, which means that it will fall on me to do the heavy lifting at least in the beginning, but I am at a loss as to how to approach this in a way that both elevates my team members understanding of how to reason around software while also not breaking my own back in the process. In short, I am looking for any kind of workshop ideas, or learning resources, that I could share with them on topics like GRASP and SOLID, or object oriented design in general, and how to structure such workshops in a productive way.

Edit: clarification and further background

In an attempt to keep the question short, I think I may have neglected some key points in our current situation. The rewrite I mention is more akin to a "refactor into a new platform", spurred on chiefly by being built on and with deprecated technology that doesn't cut the mustard any more in terms of security and performance. The application is a browser-based web application, so we can switch routes in our current solution to point to our new solution with "minimum effort" and gradually replace parts of the old with the new a little at a time until it is all new. The change I mentioned above was not the only factor, but it contributes to the larger problem. Originally, the software was used in-house only, but since it fills a niche in the market, we are now selling the solution to customers. The original product owner's workflow does not match the workflow of any of our other customers and their previously hands-on management approach lead to a system where everything is connected to everything else for the sake of shortcuts that are no longer necessary or workable. Before I started working here, issues would bounce between acceptance test and development for weeks due to miscommunication. Testing meant, and to a large extent still does mean, that the support staff push buttons and see if they get the expected result. This has been a concern, as features that were considered stable and complete years ago fail on deviation from expected inputs.

This is where I see the real problem. Our development process is not conducive to quality code, and we need to do something to shake up how we work. With a new version on the horizon, I see an opportunity to do just that. I want to introduce methodological software design not as a solution to all our problems, but to slow down the pace a bit so that we may better understand not only the actual requirements on our application, but of the application itself, and how its different parts fit together to form a whole. It is not an application full of complicated business logic, it is a large collection of different problem domains which almost never overlap except for interacting with a common core-entity. There is a modular architecture in there which would facilitate development, sales, and support, but it is not going to appear on its own, and if we don't do something, we will face the same problems we always have because it is too easy to look at what we have and just do the same thing in a different language.

And this is why I am looking for advice or resources on how I can introduce the rest of the team to software design, at least enough that I can apply what knowledge I have. Especially since we are dividing the project into two phases, one phase which is a small subset of entirely new features, with a new UI and general usability goal, before taking on the task of moving current features into the new system. The first phase will be done all in house, by the three of us, and the second phase will be implemented mostly by external consultants working remotely under our review, with the three of us producing the backlog and design documentation for them as they work. I believe that phase one provides a perfect opportunity for us to cut our teeth on a new development process, provided we can get the ball rolling.

  • "that experience is purely academical". It may be worthwhile to bring in someone with experience to guide the process. It's very easy to create the same mess, but in pattern form. Feb 5, 2019 at 16:49
  • 2
    I'd reconsider the full rewrite. Rewrites often lose some domain knowledge along the way, especially since that information is not documented. It's usually possible to write new features with great architecture along side the mess, and rewrite sections and clean things up as new features come along. This has the added benefit of adding value while improving things. Feb 5, 2019 at 16:53
  • There are more reasons for the rewrite beyond jist being a mess, it is all built on technology which is woefully outdated and almost every part of it is deprecated to the point of becoming a security risk. The rewrite is necessary, even if just to replace the current framework, my worry is ending up in a similar mess as we are now, since the inflexibilty of the system is hurting sales. The hope and goal is for this to be an opportunity to actually compile domain knowledge since right now, it lives in the support and sales department more than it does with us developers
    – JimJam
    Feb 5, 2019 at 17:30
  • "This application has no documentation and no design or analytical methodology has ever been applied to the development process" - so its just like 90% of all other custom software out there?
    – GHP
    Feb 5, 2019 at 18:34
  • @JimmyHolm How about a new framework next to the existing one? Eventually, replace it, but only after growing it with the needs of the business Feb 5, 2019 at 22:10

1 Answer 1


Start from scratch & design from start ?

Sorry, but I have to challenge your assumption... You just have lost one year cleaning the mess. In this situation, it's human that the team considers a restart from scratch. But is it really with "enthusiasm" or rather out of desperation ?

Now suppose you'll start with a big design, nice documents, but in the end, what makes you think that it will be more successful this time ? With no proven practical OO design experience, what will prevent your team (after some initial design efforts) to fall back on the old programming tactics, especially when the clock is ticking and the pressure increases ?

I can feel your growing disbelief and irritation. But before you disregard my humble provocation, could you just have a look at this article, "Things you should never do", from Joël, a respected guru in our community ? It's exactly about what you are about to do...

How to go forward ? First step: build shared understanding

First of all, the quickest way to bring every experienced programmer on a sound design approach, is to organise a collective understanding of Uncle Bob's "Clean Code".

One way could be to share the chapters between you (so not everybody has to read the full book; parallelisation), and everybody makes a summary of his/her chapter for the rest of the team. After each presentation, the team reflects collectively how the principles could be used in the existing software. Or typical problems experienced because the principle was not applied.

Another alternative is to just read the book or watch the videos. The problem is that fast-track learning is one thing, but connecting the new knowledge to existing needs activates the knowledge and makes it ready for use.

If this is not enough, knowledge of some design patterns could also help. It's not the solution to bad design but it's definitively a great learning toolbox for helping to apply good design principles to practical problems (fortunately there's plenty of material available on basic design patterns and there's a nice book from Martin Fowler about Patterns of Enterprise Application Architecture in case this is the kind of software you're making).

Next step: refactor

I believe more in working software than in comprehensive documentation. Especially in a smaller team.

So instead of redesigning the whole stuff for a while and then start to reimplement with the new design, I'd rather opt for improving the existing system, with a systematic refactoring approach. Always discuss in the team what should be the next refactoring target and how to best proceed.

The idea is that after each refactoring cycle, you still have a working product. And it will give the team the hands-on experience that it lacks with real software. So the design performance will improve during the refactoring. You'll be surprised to see that after a couple of refactoring sessions, your team will start to adopt better desgin for new features/enhancements.

A final word

If a change creates such a mess, it means probably that others things are alo missing, such as a comprehensive set of automated unit tests, which would have helped to quicly isolate what's not working. So it could be worth thinking to improve not only design but also a couple of other proven development practices.

  • This is a great answer, I am not accepting it right away because I realize reading it that when trying to make my question short and concise I misrepresented our situation and reasons for the rewrite, and what I actually mean by the rewrite and I will edit my question to elucidate on that, in case it helps understanding what my goal is and if it elicits any further response based around that. Otherwise, this will be the answer I accept and regardless I will look into the resources you linked, thank you!
    – JimJam
    Feb 6, 2019 at 7:17
  • @JimmyHolm Thanks for this constructive feedback :-)
    – Christophe
    Feb 6, 2019 at 7:45
  • I agree with most of this answer, and upvoted, but, with your team, I'd avoid Design Patterns. Try a couple that seem like "obvious improvements", but more will overdo it and likely confuse both you and your coworkers.
    – user949300
    Feb 23, 2019 at 20:52

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.