Dealing with code created by other people is a fundamental skill for a developer. Give it a year and other people’s code could even be your own.
Today I’m going to look at some of the best approaches for how to deal with other people’s code, read legacy code, effectively. It’s not an easy topic to cover.
To make the process easier, I’m framing my approach through the following areas:
- Run Tests
- Fix Bugs designed for Newcomers
- Find Available Resources
- Use a Good IDE
- Read Books & Blogs
- Contribute to Documentation
- Be Considerate
Let’s get started.
Who are the lead developers? Where are they? Are they available directly in your office? If so, go have a talk with them or email them. These people should be the best sources of knowledge about a project.
Make sure you are where they are. A criticism often leveled at Zend Framework 2 is that there’s no active community. That’s not the case, as the IRC channel is active on a daily basis. So make sure you are where the developers and other team members are.
When you first start on a project, take it easy on yourself. Don’t expect to know everything right from the start. The estimates vary, but I’ve heard of three weeks to three months of daily work with codebases before a developer can truly be considered productive with that codebase.
Some people have the misguided perception that you can, somehow, just jump in and instantly be productive. Perhaps they’ve watched too many Hollywood movies like Swordfish.
Codebases take time to learn as they’re invested with the ideas, preconceptions, beliefs and approaches of all the developers who worked on the project. Given that you’re new, you won’t have any of the background knowledge.
Here are 5 good ways to get started:
- Take time to step through everything
- Ask questions
- Setup a test installation
- Attempt to use the test installation
- Read through the code comments and related documentation
Don’t be hard on yourself, give yourself a chance to make a good start. After a while, you’ll start to have a better understanding of how the application has been put together.
At this point, start to move faster by asking questions of other developers and senior developers. You would have built a list of questions as you went through the codebase.
Take time out to ask the other developers for answers to your questions and queries. Don’t be shy, jump in and get the answers and input you need.
Any good codebase should have tests. If it doesn’t, that’s not a good sign. It needn’t be insidious — it could just be a developer or development team who’d never implemented testing — but I’d be more than a little concerned if there were none.
If there are tests, run them. Do they pass? I’ve come across more than one source codebase which has a suite of tests which no one seemed able to actually run. Have they been kept up to date?
Now you’ve tried running them, have a good read through them. If they’re well written, they should describe how the application works, what it’s expected to do, and how different components hang together. Make sure you take the time to do this, as it can be quite insightful.
Fix Bugs Designed for Newcomers
Another easy way to start out is fixing the bugs targeted at newcomers, or more junior developers, on the project. Two good examples are Joind.In and ownCloud, the bug tracker for the latter you can see in the screenshot below.
You can see these tickets have been clearly marked. Have a read-through and get involved. These bugs won’t be highly technical, but you’ll be able to ease in to the project, building your confidence and knowledge.
While glory and technical complexity can be great for the ego, when things don’t work or take too long, they don’t do any favors for your pride and enthusiasm. Start small and ease your way in.
Find Available Resources
One of the best things you can do when taking over a codebase, or when coming into an existing team, is to gather as many resources together as you can. Not sure of what to look for? Here’s some ideas to get you started:
- Do you have access to the mailing list archives?
- Is there a project or company wiki?
- What project documentation has been compiled?
- Have you read through the version control history?
- Have the contributors written meaningful commit messages, consistently?
Use a Good IDE
Good IDEs are worth their proverbial weight in gold. Whether you’re a Ruby, Python, Go, Java, PHP or other language developer, find a good IDE either specifically dedicated to or suitably customizable for your language of choice.
I appreciate some people are purists, preferring VIM or Emacs, and that’s OK. But I’m an IDE lover and my IDE of choice is PhpStorm. There are plenty of others, such as Eclipse, TextMate, SublimeText, and VisualStudio.
Once you’ve found the IDE for you, start making use of the features it offers. I’ll make reference to PhpStorm specifically here, but apply these principles to your IDE of choice.
Start stepping through the code and see if it complies with a standard. This needn’t be a formal standard, such as the PHP PSRs. But have the developers followed a consistent style, or is it all over the place. Use tools such as a mess detector and cyclomatic complexity tester to start to gauge the quality of the code.
Is there any code documentation? If so, your IDE should be able to make use of it as you inspect the code. Next, use a step-through debugger, such as xhprof, Xdebug or Zend Debugger, and run the application, seeing how it works.
What does it do? What data structures does it create and make use of? Does it repeat code blocks unnecessarily? There’s far more than I can cover here, but use the features your IDE provides as you go through the code to make your life easier.
Read and Learn
This one’s a stand-out for me personally. The more we learn, the more we can grow and — as a result — do. We’re not the first to have tread the path we’re on. Many, many, others have come before us and made plenty of the same mistakes we’re likely to make.
Save yourself a bit of time and do some justice to their hard learned experiences by learning from them. So many of the better developers are also authors and bloggers.
One of my personal favorites is Martin Fowler, who also happens to have published a great book on the topic of refactoring. There are also other excellent books, such as Design Patterns, and websites such as SourceMaking.com.
Do yourself a favor and continue to invest in resources such as these. It’s not always easy, but it can be tremendously rewarding.
Contribute to Documentation
This is one which I don’t do enough of. It’s easy to be an armchair critic, sitting on the sidelines and criticizing a codebase, framework or other kind of software project. Instead of doing that, get in and get involved.
Documentation isn’t for failed programmers, designers or non-technical people. Some of the largest projects actively suggest that the best place to start is documentation.
One of the most prominent projects which does this is the Linux Kernel. What better way to learn something than to document it? After all, if you truly know it, only then can you document it.
So if it’s an open source project, get in, find out about it, read through the code, make notes as you go along, then contribute to the documentation. If it’s an internal application, be the first to start documenting; even if for no one else but yourself.
Perhaps there’s no documentation to speak of; a truly horrid place to be. But every project has to start somewhere. As you work through the source code, write down what you know.
Some of the best developers I know, for example the lovely Lorna Jane, started blogging this way. She blogged to keep a record of what she was learning, which later turned in to one of the most popular PHP blogs around.
The last point: Be considerate to the developers whose work you’re reviewing and building on. You don’t know where they were in their career and education, or what restrictions they had on them, when they wrote the code you’re now coming up to speed on.
What’s more, at what skill level are you at? It can be easy for us, when we’re younger, newer, and less experienced, to be judgmental of others.
We think we know it all and that our expectations, concepts and approaches are the true and correct ways to go. But is that really the case? I like to believe that, as we mature, and grow a bit older, we also grow wiser and become more accepting of the wide array of approaches to software development which exist.
We may not need to agree with them, but they’re not necessarily wrong. They may have a lot to teach us, which can help us grow. So always try and be considerate of other people and the position they were in. Don’t be the obnoxious newcomer, pointing fingers and laying blame. After all, that helps no one, especially you.
There’s loads more that you can do to make working with other people’s code a more manageable process. What methods, tips, tricks and tools do you use?
Matthew Setter is a software developer, specialising in reliable, tested, and secure PHP code. He’s also the author of Mezzio Essentials (https://mezzioessentials.com) a comprehensive introduction to developing applications with PHP's Mezzio Framework.