Editor’s Note: This is the first in a five-part blog series on refactoring and modernizing PHP applications.
We’ve all heard the expression from the children’s story: “slow and steady wins the race.” But what does this have to do with refactoring? And how can this help us to modernize our applications?
I have a long-standing client who has a complex piece of software that I developed for them some time ago. From time to time they approach me and ask me to make improvements to the software, which I am almost always happy to perform. And like any good client they want an understanding of the cost before they move forward, largely to ensure that the cost-benefit analysis makes sense. And so, they ask for an estimate.
I’ve written on estimates in the past. I don’t like them, largely because they can tend to box you into a particular position that may or may not be correct.
Like many mentors, instilling best practices is an important part of what I do. And I encourage my mentees to follow best practices, including testing. For example, I encourage them that code isn’t done until it’s been properly tested, and that the higher the test coverage, the better the outcome overall.
Yet even as an advocate for testing best practices, I’ve steadily learned that “well-tested” or even “completely tested” doesn’t always mean “100% test coverage.” And while this might seem a paradox, it’s not.
The biggest complaint people have about object-oriented design is where they put all the “glue code” that ties together a bunch of objects and makes them work well. For many, this place is the controller, but as I’ve covered before, most of this logic belongs in the model. In fact, the model should be where all business logic resides. And yet, it can still seem difficult to figure out precisely how to manage all of these behaviors in one place and still follow the best practices of object-oriented design and development.
But there is a way to accomplish this that won’t make you crazy. It’s accomplished by making use of “services” – bits of code that act as the “glue code” for all the different objects that have to operate.
Green field projects are certainly rare, but they hold a certain appeal over developers. The ability to ignore all the mistakes of the past, and instead focus on new architecture, new ideas and new methodologies is enticing. And yet, every pile of legacy code spaghetti out there was once a green field project, filled with the majestic hopes and dreams of the engineers who worked on it. What happens?
I know many developers who believe that code simply gets worse over time, that technical debt accumulations are inevitable and that bad decisions haunt us forever. But the truth is that code doesn’t rust. And that means that our ability to make changes is directly related to how well we create the code in the first place.
Few things bring out fights among programmers quite like a fight over documentation. There are many schools of thought, from “document every line” to “let the code self-document.” For the most part, PHP seems to have agreed on a generalized standard for documentation in code, called PHPDoc. Actual blocks of documentation are referred to as “Docblocks”*.
But within PHPDoc, there are many different styles and behaviors. And so, I have developed what I consider to be my “best tips” for documenting your code with Docblocks.