4w350m3.

In the previous post, I covered the steps for preparing to really dig into a new project. Now that you’re ready to go, here are six steps that you might find useful.

1. Get it running
2. Do very high-level overview
3. Dig into specifics
4. Switch to clean backup or rollback with version control
5. Cleanup unused code
6. Fix some small bugs or issues

Get it running

I’m assuming you’re doing development on your local machine, so the first step is going to be getting the project running correctly. In part 1, I emphasized the importance of having a reference copy so you can tell the difference between config issues and things that are just broken. Get things setup, compare to reference copy, run through some user flows on both sites, and make sure you’re all set.

Do very high-level survey

I start with the basics, like where are the various config files, does it follow MVC or another design pattern, what’s the basic flow from file to file, etc. This is usually accomplished by tearing up the code, throwing debug statements around, etc. Take lots of notes, and add comments to files as you figure out what they do and why they’re there.

Dig into the specifics of the code

Once you have the higher-level stuff, try to figure out the core of the app and how it works. There are common things that most sites have, like authentication, but most projects have their own special sauce that’s unique. Sometimes it’s for good reason, often not, but you’ll need to understand it. Figure out what’s unique about this project and spend some time really mucking with the code here. Put in lots of comments and debug statements, and really try and understand the rough outlines of what the code is doing.

Switch to clean backup or rollback with version control

Depending on the damage you’ve done to the code, you might want to go back to a clean copy of the code, or revert your changes using whatever version control you’re using. However, this does mean you’ll lose those comments you made, so it’s a judgment call. The alternative is removing all your debug statements and other changes, and running through the app to ensure you haven’t introduced new problems.

Cleanup unused code

I hate code clutter. There’s nothing worse than starting a new project and seeing things like this:

• functions.php
• functions2.php
• _functions.php
• functions_by_brad.php
• functions_new.php
• old_functions2.php

Equally bad are files where 75% of the code has been commented out and just left hanging around. These are all consequences of not using version control properly. If at all possible, put the project in version control, figure out which of these files is currently in use, and clean the rest of this cruft out. This is optional at this stage, and sometimes I wait until later in the project when I’m more familiar with what goes where.

Fix small bugs or issues

Now that you’ve got a good high-level understanding of what’s what and how the program execution flow goes, and maybe even cleaned up some stuff, it’s time to add your own mark. I like to start with small bugs. The smaller the better, because you’ll spend time looking for where to make a small change, which gives you better understanding of the code. Big changes at first can leave you feeling overwhelmed. So look at the list of bugs or features that the client has provided and try to sort them in terms of anticipated difficulty and tackle the first couple that seem like a snap to fix.

You’ll know the project like the back of your hand in no time.

As a contract web developer, I frequently work with clients who have gone through one or more developers or development agencies and still haven’t achieved the goals they want, so they bring me in to mop up and finish the project. The sooner they call me, the better, but I often don’t come in until the situation is dire. Getting up to speed on these projects is the first step to being able to move them forward, either by cleaning them up and finishing them, or recommending the client start over from scratch. Here’s the process I use, but I’d love to know how it can be improved.

To get started, you’ll need six things:

1. Any existing notes, documentation, etc.
2. Knowledge of the platform
3. Pen and paper
4. A reference copy
5. Good backups or version control
6. Time

Existing notes or documentation

Obviously, it’d be great if you had good docs on how the project was designed and what’s where, but that’s very, very rare. Clients don’t usually want to pay for documentation, and if the developer was the type to do documentation anyway, I probably wouldn’t have been called in. So your options are to either forget it, which is usually what happens, or to talk to the previous developer and get the info from them directly. If you have access to them and they’re willing to help, take advantage of it. Half an hour on the phone can save you hours later.

Knowledge of the platform or framework

If the site is built in Drupal and you’ve never used Drupal, you’re already at a disadvantage, because you’re going to be trying to learn both the platform and the project simultaneously. If I’m working on a new platform or framework, I like to take an hour or two to really try and understand it at the high-level. Most good frameworks and platforms today have a “getting started” guide and often a few demo projects or applications that you can play with and examine the code for. Read through the docs, look at some code, download other people’s apps if you can and look at those, just to get a feel for the style and flavor of the platform. Try and look at official code if you can, or at least projects that appear to have been coded with good practices.

A reference copy

This one depends on exactly how you’ll be handed the project, but I’m often just given access to the server or get the project files sent to me. I prefer to do my development locally, so the first thing I’ll have to do is get everything setup on my own machine. Almost by definition, this project is usually broken in the state that I receive it, but it’s hard to know exactly what is broken and I need to get it setup correctly. So I find it useful to have a version running somewhere (usually on the client’s server) that is as functional as possible. That way, when I setup my local copy, I can ensure that I have things configured correctly, and the issues I’m seeing are the things I’ll be fixing, not just me not having things setup right.

Good backups or version control

You’re going to be tearing the code up, editing, adding comments, tracing execution, etc. and you don’t want to introduce new bugs that you have to track down as well. Obviously, using version control software like Git or Subversion is ideal, but even just a simple backup of the project files will do in a pinch. The important thing is to have the peace of mind that you can rip into the code as needed, because you have a clean copy to revert to.

Pen and paper

You’ll be adding comments directly to the code, but you’ll also want to make notes on higher-level architecture details that span multiple files or folders, questions that you have that you want to remember, etc. Just keep a pad and pen by your keyboard and jot down notes as they occur to you. They probably won’t be useful past the first few hours in the project, but they can help you avoid losing track of questions or realizations you come to.

Time

Obviously, it depends on the size and scope of the project, whether it was done from scratch or in a platform like Drupal or WordPress, and the quality of the codebase in general. However, I generally find that 2-3 hours of dedicated time can usually give me enough time to at least understand the high-level outlines of a large project, and really understand the problem areas of a small project.

Tomorrow, I’ll go into detail about how to actually jump into the code and start cleaning things up.