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.
This summer, several PHP developers (myself included) will be embarking on a 16-city speaking tour called The Crafting Code Tour. This multi-state, multi-country event is designed to bring great outside speakers to user groups around the United States and Canada. Today, I’m pleased to announce the dates for The Crafting Code Tour!
We’ll be visiting the following locations on the following dates:
When a discussion thread on the PHP user group leader’s list started up about the cost and potential for outside speakers, most people generally agreed that user groups have a hard time wrangling outsiders to come and speak. The cost of travel is prohibitive, and small user groups often have trouble getting the funds necessary to bring in someone from far away. The internet surely brings us closer together, but there’s still no substitute for the in-person speaker who can share knowledge and experiences, plus a beer or two.
This challenge of bringing in outside speakers prompted an idea. What if, instead of organizing one speaker for one user group, we could organize a tour of speakers to travel to multiple user groups? What if, instead of expecting the user group to pay the expenses, we sought the help of those who care the most for the community? What if, instead of one speaker bearing the burden of travel, we distribute it to many speakers, each having a small role to play in the overall event?
It never fails. Someone will write me after reading my book or taking a class with the same story. They were so jazzed: they felt like they were on top of the world, ready to attack their next programming task with vigor! They had studied hard, connections had been made, understandings had been formed. And then, inevitably, reality sets in. They look at their code, same as it was before, and realize: this is going to be harder than I thought.
It can be easy to feel dejected when looking at a pile of code you inherited from four generations of programmer ago. None of the best practices or principles. No tests. Hell, you’re lucky if you even have objects that don’t rely on PHP 4 style constructors. You’re in legacy code hell.
Bad code. Most of us have seen it before. And most of us are aware of concepts like “technical debt” as it relates to software development practices. But what most of us never actually think about are the specific business challenges posed by code that is loaded with technical debt and difficult to maintain.
Refactoring code is often at the bottom of a business’ to-do list. Features, deadlines, goals and moving the project forward are crucial things that businesses are focused on. There’s a good reason for that: customers don’t buy software because it’s easy to maintain, they buy software because it solves their problem. And thus, refactoring doesn’t seem to have inherent business value.
Many people wonder how they can improve the overall readability and cleanliness of their code. It seems impossible to understand exactly how to rewrite code in such a way that makes it clean, easy to understand and simple to work with. But clean code is about a few simple principles, one of which is reducing overall code complexity through a series of simple steps.
I’ve been working on a new book on clean code for the last few months. While I know that I’ll never answer all the considerations regarding clean code, I believe that I can make an impact in showing people how to measure their code’s cleanliness, and know exactly what they need to fix. One metric that I’ve been focusing on for the last few weeks is code complexity.