I'm working on a medium-scale software firm and my current project is on a government agency. This agency's scope is nationwide and we are creating automated system for them.

Because of the large-size nature of the project, it is divided to 12 major phases, and aside from this reason, the project is divided because of bidding purposes (e.g. It is not always that the same company will be hired in every phases)

Here is the main problem: We won on the bidding of the first phase. Now part of the contract is to

  1. Make full and proper documentation of the system, and;
  2. Code the system on a way that future system can be easily integrated on it, and can be easily maintained.

After some time, we again won the second bidding and that is when I was hired. Now while team members introduce me to the system and to my specific task, I observed that cannot easily "dive" to the previous delivered system because:

  1. The documentation that is the end-product of phase 1 is not that comprehensive
  2. The codes (made also from the previous phase) are not that well-designed (e.g. Does not follow clean coding; no centralized convention; does not follow OOP principles etc. other technical stuff.

I asked my far more experienced coworker on this and we are on the same position and because of this unanimous decision, I want to suggest a redo and perform a complete overhaul before actually starting the real task of the 2nd phase. How can I tell suggest my manager / company head that smoothly? This problem is not in any way to affect this government agency since the system is already live and functional. Though maybe for now the problem is not that evident, but what about if the project is on its 6th phase onward? What if the company that handles the project then will have difficulty on progressing?

I'm considering these factor on how should I construct my suggestions and give it to my superiors:

  1. They might think that the first phase of the project is [not so] total waste (in the long-term perspective)

    "I can't believe how this product quality passed"

    and might even put all the blame to the previous project manager, which is by the way my friend.

  2. The coding is not that "continuity"-friendly, and I'm very anxious [and actually not proud] if a developer from a different company see our codes and really might do bad for our reputation like:

    "I wonder how programmer of Company X create applications like this?"

    (Trust me, the codes are really messy and maybe this is harsh, but my coworkers says that it does not meet the "industrial-level")

  3. Though I can also easily quantify why (as detailed and objective as possible), I don't know how not to give them a "The previous delivered system is of bad quality and as the management you should feel bad on allowing this" vibe.

My manager and CEO are very friendly and kind (They do fist bumps to us employees every now and then- that kind of friendly) but they are also very emotional. I don't think they will approve this suggestion that easily.

  • 14
    Welcome to bespoke software development. You've just described 99% of the code created by agencies for clients. Commented Aug 26, 2015 at 5:31
  • @Carson63000 I really agree to that. I always hate it when I inherit a code that is not very "successor-developer-friendly" and it brings my drive down. But you cannot always tell people to do things the same as how you do things....
    – Gideon
    Commented Aug 26, 2015 at 5:42
  • 1
    I think you have more chance of finding good-quality code at companies developing for their own business purposes, rather than building things for clients. Commented Aug 26, 2015 at 5:46
  • 3
    Recommended reading: joelonsoftware.com/articles/fog0000000069.html Commented Aug 26, 2015 at 18:40
  • At what point did the company have sight of the end product (or a substantial sample thereof) in order to determine the scope of work? Before signing up to the contract, or after? If after, does the contact permit withdrawal once the scope has been determined?
    – user52889
    Commented Aug 26, 2015 at 18:50

2 Answers 2


As several commenters have said, this is the real world of software development. It's a shock when you have to learn that the vast majority of the working world is nothing like textbooks or blogs.

You're not going to get what you want

You might as well take a total rewrite off the table. It wasn't part of the bid, ergo, it would be extreme malfeasance for your manager to let you do it. The project was bid and had to be bid as if the first part was done correctly.

The only way that could have gone differently is if your company was replacing an incumbent company that was known to have done it wrong. You absolutely are never going to win a contract by saying "I know I promised to do X but I didn't, so please pay me extra so I can fix that before doing the next task." And they would have to ask for extra money to do extra work like you want to do.

Not only that, a complete rewrite would almost certainly result in the introduction of a whole different set of bugs that would be sure to be noticed and would have to be explained. I don't care how good you are, you are not going to be able to rewrite a complete mess into better order and not introduce bugs--even if those bugs are related to the fact that you have zero domain knowledge at this point.

What can you get

I think you're in a good position to bring about an orderly rewrite while keeping the system going. If you and your colleague were not in fundamental agreement that the system needs to change, you'd probably be SOL, because you would each approach areas of the system completely differently and with management basically not present at a technical level, you'd have no recourse other than just doing what you could on the parts you "own."

How to get there

You can't tell your boss that the code is crap and it's all his fault. There are very few people who are going to say "Oh, well thank you new person for coming on the project and setting me straight. We'll start changing everything to suit your revealed wisdom." Even if there weren't all sorts of constraints preventing this (see above), it's just not human nature to do that.

You will have to set some kind of expectations that the schedule and budget are likely to be way out of whack because they are based on incorrect assumptions. So where you can, you can present it as the system needs to grow in a way that's different from how the original developers apparently foresaw, so you need to build in extension points/seams where they don't exist as you go.

Unfortunately the reality is these opportunities may be fewer than you'd think, because in these types of organizations it's relatively common for projects to be bid without even asking developers how long they think it will take. They simply tell you how long you have to get it done.

The Technicalities

The way you actually do these types of refactors is you knock out individual subsystems one at a time. Build gateways that inject the one or two things that subsystem needs to know from the giant seething mess at the center and then in the unlikely event that you get the giant seething mess at the center cleaned up, you can remove the gate and inject things properly.

The good news is that the parts you touch the most are likely to be the first things you clean up, and you will likely get to a point where it doesn't even bother you there's a seething mess beneath your feet.

Meet with your coworker daily or weekly to share details he or she (and you) will need to know to keep the work consistent.


Suggesting a complete start over and rewrite is not going to go over well. You can suggest gradual refactoring and even that is a hard sell. This is especially true if the code was accepted by the client already as then the contracting company would have to pay out their own pocket for the rewrite and they would lose money on the contract. There is roughly a 0% chance that this would be well-received and even less that it would be done.

In fact some of those bad choices may have been at the specific request of the client. You don't know the history of why they did what they did.

What you do instead is make suggestions for improvement on each module you touch. Even then, if many other areas are affected, expect a good bit of push back. If it is something that is self-contained, then you can improve it more freely. And don't do so until you have a good working set of unit tests. You will lose all credibility if your improvements break something else or introduce new bugs.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .