This entry is part of an ongoing series involving the review of a code sample and it’s refactoring. For the original code sample, see here.
The topics discussed in this entry may be fairly advanced. Please feel free to ask questions, and discuss best practices.
If you’ve been following this series from the beginning, take a moment to look at the original code sample and compare it with where we are now. We’ve come a long way!
There is one last area that I want to address, and this has everything to do with object-oriented principles and code reusability. For those who are familiar with OO programming, they realize that the use of classes does not make something object oriented by nature. In this final part of the series, we’ll move one step closer to being object-oriented, by introducing the concepts of request and response objects.
At the moment, our object takes arguments like most functions do. This has some limitations. The first limitation is that the object must be aware: that is, it must have an understanding of the request it is being passed, and the response that it is getting from Twitter, as well as the response it will give back to our application. This means that in the event that something ever changes about the way that response is organized, we have to change this code, explicitly. I would like to avoid that.
If you need a sample of the code, please visit here.
One of the first things I look for when I check out code is how is the code organized? Is it laid out well? Is it coded to a particular standard?
In our code sample, the first thing we should address is how does the code look. There are a number of suggestions I would make immediately. Let’s dive in.
There are no DocBlocks or clear coding standards.
No clear coding standard jumps out at you right away when you read this code. There’s a lack of consistency, but beyond that, code completion is hindered by a lack of standards. Also, there’s no DocBlocks, which would help improve the documentation of the code.
There are lots of coding standards out there: PEAR, WordPress, Drupal and Zend Framework all have a coding standard in place that you can adopt in your own code. I highly recommend it.
The first thing I might do is add some DocBlocks. It will help us understand the code better.
On Wednesday, August 12th, we had a meeting of the DC PHP Developer’s Group. Keith Casey of Blue Parabola led a code review of a member-submitted sample. The review was informative, educational, and helpful. With the permission of that member, I’ve decided to write a series on the tools for reviewing code and re-factoring it.
The code sample (included below) isn’t perfect. It needs work, and we’ll be working on it over the next few articles. Along the way, we’ll talk about strategies for identifying weaknesses, candidates for refactoring, and methods for writing better code before you get to the review stage. We’ll also refactor this into something more usable, and end up with a finished product that’s better than when we started.
The knowledge gained is based off the DC PHP Developer’s Group, as well as many notes that I put together. The refactoring process requires a lot of thought, and so this series will contain six more entries, starting with the first one on Monday. But before we begin, here’s the code sample we’ll be working with: