I've been tasked to correct some issues on the backend of a large website project that has been outsourced for some time. The original developers and us are not on good terms so it's not feasible to get them involved.

The technology stack is as follows:

  • MySQL 5.x
  • PHP 5.3 (and a variety of supporting libraries)
  • Apache with mod_rewrite

The problems I am facing are:

  • No documentation, not even comments
  • 4 index files in root, plus 2 main files in a combo of php and html and 1 default.php, the referenced index file in .htaccess references their local test server.
  • Duplicate file names / files
  • Atrocious file system layout ( ultiple js folders, multiple script folders etc )
  • Reliance on original mysql functions ( not mysqli or PDO )
  • multiple frameworks, JQuery, various marketplace API's etc.

It has been a highly frustrating several hours trying to sort out where to begin with this mess, let alone how to fix the items I need.

So my question is: What would be the best place to start or If this was dropped on your lap, how would you approach it?

I know this is subjective, and opinions are what I am looking for, so any advice is appreciated.

  • 7
    @downvoter: If you downvoted due to subjective nature, please suggest the appropriate resource to use in order to get the advice I require. I couldn't think of one...
    – Robert H
    Jul 12, 2013 at 16:03
  • 1
    I agree, this question is perfectly fine. Comment +1 and Question +1
    – pattyd
    Jul 12, 2013 at 16:04
  • 5
    How would I approach it? With extreme trepidation, that's how. God help you.
    – Aaron Miller
    Jul 12, 2013 at 16:09
  • 2
    If you can work out a time frame and budget, a redesign might be the best answer.
    – ajp15243
    Jul 12, 2013 at 16:11
  • 2
    "highly frustrating several hours" ... for a bigger application it may take weeks (or more) to adequately understand it. Jul 12, 2013 at 17:34

6 Answers 6

  1. If it ain't broke, don't fix it. I'm assuming the code has been running functionally for some time, and your business process has assured the previous developers have met the SLA you are now shooting for. Which means, in lack of bugs or new feature requests, you don't have to touch anything ever again. Of course you do but it's important to understand this point first. Your goal is not to rewrite or even to understand a complex project. It's to be able to ascertain enough information on requests you do have to make to fix relevant pieces and touch relevant code only.

  2. Strategies for making isolated changes are very different than strategies for understanding or re-architecting whole code bases. If you are asked to make a small change, often the best thing to do is enter your application, probably via an HTTP request in your case, while having your server running under a debugger. Now you can simply watch the logic the code is following and have an idea of the relevant architecture. The debugger is your tour guide through the fog of war.

  3. Consider making a small change with some code rot. Often you will be able to say, "I know this code change will work, even though it's probably bad design." This can be a reasonable choice. But of course you do need to establish that you do in fact know the code change will work, so you will have to study relevant pieces some amount. Keep security risk in mind - if you slap something together and it works well on a few test cases, do you understand the system well enough to be wary of disastrous corner cases?

  4. Your early steps should include getting your code under source control and learning the moving parts in production. Source control is a big one, obviously, and you want to keep track of changes that you make very well. If you have not been in the habit of making cohesive git commits, this would be a good time to start, because you're likely going to want to be doing things like cherry-pick and subtle rollbacks more than when working on code you know well. Branch intelligently: now in production, changes I've made that I think are safe, changes I've made that are just poking around to see what stuff does but I might want to refer to later anyway.

    But beyond that, think of questions like: do you know your environments? If you run the source from your laptop will it break things in production? Or is there a safe development environment? Also, think of components outside the software and account for them - build system, unit tests, logging, monitoring and error notification, etc. It hurts to make a broken change then discover you also broke the monitoring on it.

  5. Be prepared to make the case for an expensive redesign or rearchitecture. As maintenance tasks you have to do on this project get larger in scope or more frequent, and if you really are convinced the code you are working on is poor quality, you will simply have to make the case that replacing it is cheaper in the long run than maintaining it. Find pieces that can be affordably rewritten rather than rewriting the whole thing. This may mean isolating a data layer or logging system, all one component at a time.

    The extreme case is of course to throw out the entire project and rewrite in, say, Ruby from scratch, but if it comes to this, it's probably more because you were not savvy enough than because the code was that awful. You should be able to identify pieces that you understand why are awful and how to turn them into maintainable components and affordably rewrite those with a general sense of the scope of what you are getting into. The worse the code or the less savvy you are, the bigger the piece, but throwing out everything will be a last resort.

  • 3
    Good answer, but I'll add another piece of advice: Keep track of all the changes you made, if the code is not under version control, then put it in a version control first before touching anything.
    – Lie Ryan
    Jul 12, 2013 at 21:36
  • Agree with @LieRyan : Step 0: Source Control
    – WernerCD
    Jul 13, 2013 at 3:14
  • 2
    And if you can find old versions (on people's PCs, in random backup directories on the server, in backups of the server, etc) check them in as vendor branches. Jul 13, 2013 at 7:22
  • @djechlin regarding point #4-> I'd add creating a staging server if one does not exist. I my case the only data I have is production data. That way the code can be reviewed,altered and manipulated without bringing production down.
    – Robert H
    Jul 13, 2013 at 11:10

I would start by hunting down and fixing the bugs I was tasked to fix. Use bug hunting to get familiar with how the code works. Along the way make mental notes about any glaring problems I might see. Since you're using mysql_ functions, I'd pay special attention to fixing any possible injection problems.

Resist the urge to launch immediately into re-write mode. For starters, you may not have the specific domain knowlege necessary for such a step at this point. Better to at least have a few months with the existing code base before you start evaluating the possibility of a rewrite. It may be, for example, that some of the 'problems' you see in the code end up making more sense to you as you get familiar with it.

  • +1 As a young developer, the times I've been presented with large, new codebases, I got to know them by doing bug fixes until the overall architecture started to make sense to me.
    – Kevin
    Jul 12, 2013 at 18:29

I'm going to ignore the possibility of a rewrite, and only address how to attack this particular problem, assuming a rewrite is not in the cards.

First thing to do: spend the time to figure out what it's doing and how, and document it as you go. Then, break it down in to smaller pieces. Instead of being overwhelmed by the massive size of the project, figure out what things you can work on atomically. Some suggestions:

  • Abstract out the database calls in to a class (either your own, or PDO, or another library)
  • Restructure the assets so they're more logical
  • Consolidate the front-end libraries so it's only using one

I'm sure there's a dozen (or a hundred) different areas that need work. Don't think about that; think about the first one to attack.


My preferred approach is:

Set up some basic documentation yourself

  • class diagram

  • ERD of data

Next debug through some parts of the application to get an overview of the architecture. From that you can construct an abstract view. Again, document it.

By the time you are at this point, you should be more familiar with the project.

  • 2
    I think it's unrealistic to come up with a global class diagram, and actually counterproductive to try. Especially if the code is not OO. But +1 for debugging.
    – djechlin
    Jul 12, 2013 at 19:01
  • @djechlin PHP can be written OO. There are cases where a class diagram could be useful, but it should be separated based on layer Jun 6, 2018 at 21:20

I had a similar issue a couple of years ago.

After a lot of research, I found out it would take much less time to build a whole new system than to try to fix the one that was ready. Most important: try to fix that messy code would certainly leave lots of security holes.

As the only think that was truly relevant was the db (which was also a mess), I first planned a db scheme and built a script to migrate the db to fit my scheme and built a new application the right way.

I don't know if you may do something like this but maybe this line of thought may help.

  • 1
    it's really going to depend on how broken the existing system is. if there's lots of things wrong with it, then yeah, a redesign is probably the way to go. if it's just one or two little things, then it's better to buckle down and decipher the existing stuff Jul 12, 2013 at 16:18
  • According to what he wrote it's not one or two little things...
    – Robyflc
    Jul 12, 2013 at 16:20

I think that I would approach it one of these ways:

  • Talk to the previous developers even if you are on nasty terms

  • Talk to somebody that was around when the website was first developed/in development

  • Do a complete redesign

  • Read through all of the code and make any changes to each line that needs to be changed
    (this will take a long long time though)

  • Tell your boss that you are not in a position to do this

  • Ask your boss to hire more people to get the job done with you

  • Try to find out exactly what each page does before doing anything

That is all that I can think of at the moment, but if I have any other ideas I will edit my answer.

  • 3
    "Do a complete redesign" did you consider the cost involved with this?
    – Kermit
    Jul 12, 2013 at 16:31
  • 3
    Every single bullet point in here is terrible advice. "Tell your boss you can't do it"? That'll look great come performance review time. "Hire more people"? Can more people not understand something faster than one person can not understand something? "Read through all the code"? I don't even need to read all of my code to make a change, and if I did I would never be able to make any change. "Talk to previous developers even if on nasty terms"? At best and more realistic they'll be useless, at worse they'll sabotage.
    – djechlin
    Jul 12, 2013 at 17:24
  • 3
    How are you supposed to do a complete redesign of a system whose logic you don't even understand yet? etc., etc., etc...
    – djechlin
    Jul 12, 2013 at 17:29

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