7 Best Practices For Every Developer
There are literally thousands of best practices, in fact I have learned so many over the years, I have probably forgotten more than I can actually remember or conscientiously apply. 
You have best practices for software architecture, exception usage, team development, optimization, security, etc. What I have tried to list here are the lesser known techniques I have applied to my daily bump and grind, to make better use of my time. I have tried to keep the list generic as possible, so these techniques can apply to any developer (single or team player, PHP or C++, OOP or Procedural and so on and so forth.
I look forward to hearing your best practices. Ideally I’d like to keep this blog updated frequently and grow it as a compilation of individual experiences. I have tried to do this several times on various forums, but the topic never really blossomed into what I was hoping for, so I figured I’d list several and get the ball rolling.
1. Keeping tabs on your TODO list
Leaving code partially unfinished or incomplete is a frequent event. What techniques do you use to make sure everything gets finished? I’ve seen some people use a simple TODO sheet in notepad, or physically write tasks down on a quick card or sticky pad. I see few problems using this approach.
- Paper is not as accessible as electronic documents and it’s a waste on the environment.
- Notepad, like paper is not easily kept synchronized with the actual code base.
Ideally, you want to keep this TODO list in the actual source code. Keeping simple in-line comments like the following works flawlessly.
// TODO: Some task that needs completion
That is all that is needed to keep your tasks organized and entirely syncronized with what is actually happening, not to mention it’s a lot less work.
There is one minor issue and that is, tasks are not centralized like paper or notepad. You would have to manually keep tabs of each file with TODO comments. This is easily fixed using a simple ‘grep’ command.
grep -RnH 'TODO' /var/www/yourcode
Now when you log-in first thing in the morning, you execute that simple little command and have yourself a quick list of things to do and unlike notepad or paper, the TODO points are actually shown with the applicable file name and line number so you can quickly get to work.
2. Sometimes simple doesn’t always mean less
When we as developers begin using OOP one of the first things we do is try and compartmentalize everything. We implement objects of every kind, such as People, Airplanes, Cars, Trucks you name it. We then use those objects like so.
$person = new PersonObject();
$person->create('Alex', 'Barylski', 29);
$airplane = new AirplaneObject();
$airplane->create('Boeing', 747);
So whats wrong with the above code? Technically nothing (I hope) and it’s even easy to read and understand for a human, so what’s the issue?
Refactoring! In the world of PHP there are few refactoring tools available, those that do exist are generally just search and replace scripts on mild steroids. Now imagine you have these objects instantiated all over your code and one day, you decide that Person::create() no longer makes sense and you feel your code would better reflect reality if you renamed the method to Person::giveBirth() – see the problem?
Because refactoring is typically done using search and replace (even if replacing is done manually) being able to find all those Person::create() instances using a simple ‘grep’ would be a nightmare. If you had 10,000 instances of XXX:create() and only 20 of them were Person objects you’d be crying by the end of the refactoring process.
What I advocate, and practice in general (possibly at the expense of slight redundancy) is the convention of verbNoun for all method names. So instead of Person::create() I get Person::createPerson() and while it it might feel weird at first I promise this practice to pay off many times over in any future refactoring. A quick search and replace of createPerson() will/should only return those unique instances and not the 10,000 instances it would have before.
3. Keep things explicit and avoid developer voodoo
Often when we read code (either our own or someone else’s) we struggle to understand a function or even a single line of code, because it uses some weird convention or auto-magic behavior only the original developer was intended to understand.
I do occasionally use auto-magic techniques (ie: __autoload) however only when it makes a lot of sense to do so and will not negatively affect my trying to find something using search. For example, one code-base I recently worked on loaded their templates using the file-name only and ignored the extension. When I searched the code-base trying to find where this template was loaded I found nothing when I searched for ‘whatever.tpl’.
This was extremely frustrating as I knew the change would immediate but finding the place in the code where this change needed to occur was like finding a needle in a haystack, all because of ‘developer voodoo’. I couldn’t understand why they would ignore the extension, but I assume it was so if they decided to change the extension of the file from TPL to TPL2 they would only need to make one change to the template loader code. Clearly not enough thought was put into this decision, as finding a template extension anywhere in source code would be trivial using ‘grep’ whereas finding a file-name was more a PITA.
The rule is simple: “Don’t write code that just works, write code that someone else can understand.”
Following this simple principle will no doubt make your code more efficient, less buggy and easier to change and/or understand, even for yourself, trust me.
4. Avoid variable parameter lists
Similar to tip #3 I dislike variable argument lists because they are developer voodoo and not explicit. For starters, automatic API documentation generators like Doxygen or phpDocumentor will not proper document your API for any method that uses variable arguments. Secondly, unless developer voodoo becomes convention/standard it will be confusing to any new developer who sees the same function called several times throughout the code but with varying arguments.
5. Keep the constant on the left hand side inside a conditional
if($value == 12345) BAD PRACTICE
if(12345 == $value) GOOD PRACTICE
If you ever accidentally type ‘=’ instead of ‘==’ you will be notified by an error telling you assignment of a constant is illegal, essentially catching an otherwise difficult to find bug.
6. Don’t comment your code!!!
How many times I have seen comments like:
// Initialize variable with data from $_GET
Why? What are we programming in assembler, is variable assignment is that cryptic?
That is a classic case of over commenting because “we” as developers think it’s the best thing to do.
I say, comment sparingly…in fact if you need to comment, consider refactoring your code so it self describing. Use real variable names and methods names not abbreviations. Mnemonics are for assembler and 1950’s when memory was a limited resource.
Make your functions and your code essentially spell out what it is you are trying to do and then you don’t need comments, except for rare occasions like describing a hack or a weird requirement due to a external dependency or something.
7. Write your tests before you write your code
This is a frequently touted best practice but only if you incorporate TDD into your daily SDLC, admittedly I don’t. However I still think it’s important enough to include in this list of developer best practices as it promotes simplicity and loose coupling and assists you in getting the interface contract right, the first time.
Tightly coupled code is a PITA to change and it’s even more of a PITA to write test cases for. If that green light, letting you know your tests passed doesn’t do it for you (aka: confidence builder in your software) the fact that you intrinsically will write better code should be enough incentive to start writing those tests and writing them first!!!
Conclusion
Best practices are entirely subjective, so I am in no way advocating that these will cure all your programming headaches. However they have proven useful to me on a day to day basis and my hope is they help you too. I also hope you share some of your best practices with me and any others who might read this blog.
What are your best practices? Try and keep them generic and not specific to any one language (unless it’s PHP).
Cheers,
Alex
— Manually Entered Comments —
seifer | You mentioned about the practice of naming all method names in adjectiveNoun convention. Err, verbNoun convention, you mean?
Alex | Yes, my bad. I did mean verbNoun
PCSpectra Phone Number Change
We were starting to receive a large number of wrong number phone calls from the same people so we decided to bite the bullet and purchase a official “800″ number.
This does offer greater flexibility for our consultants, as our partners are now capable of reaching them via one number regardless of whether they are on the road or at home. The 800 number acts as a single point of contact and routes incoming calls to appropriate lines (office, home, cell, etc).
This will allows us to serve our partners more effectively and efficiently — just like properly designed software. 
Kind Regards,
The PCSpectra Group.
PCSpectra Version 10 Goes Live
We have finally completed the latest incarnation of our web site. Here are some of the things we did:
1. Developed a super easy CDE (content delivery engine) that allows us to quickly and easily templatize the entire site. Joomla, Mambo, CMSMS, Drupal, etc are all good, but way to complex and sophisticated our needs. Essentially our CDE generates the master template, pulls in the various parts that give the template meaning, such as title, body, etc and returns the result to the browser window. Fast, Easy and Efficient.
2. Integrated CRM into the contact FORM you see on each page, so when ever a potential partner contacts us their details are automagically sent to our CRM system so we don’t have to extract details from the email and enter those details in our CRM system.
3. Integrated Wordpress RSS 2 feeds into our master template so instead of having to update a news page we can just use Wordpress to achieve the same result, but in a much more elegant fashion.
4. Contact FORM’s are a PITA so we also wanted to ensure our partners could contact us easily using a variety of methods, two of which are email and phone, so we place our phone clearly at the top right where most people’s eyes tend to look at as they browse a site. Also, we built a auto-responder which effectively eliminates our email ever falling victim to a spambot. We accomplish this by having a partner submit their email to our server and the server simply replies, which the partner can then reply to in full. Without having to type an extended message in a tiny little FORM textarea.
We’re waiting for Google to approve our request for AdSense and we’ll be integrating Google ads into our blog to hopefully monetize our work in writing and pay for some of the hosting fees.
All the web pages have been double checked to ensure W3C XHTML validation and we only use one table for layout purposes, which we swear is not possible using CSS alone — if you know how to fix this by all means let us know.
We feel the images are sharp but the color and tone is a cool, laid back professional consultant look, which is exactly what we wanted.
Kind Regards,
The PCSpectra Group.
Why software standards are extremely important
If aircraft engineering was similar to software engineering I would never fly (anyone that knows me, knows I’m obsessed with flying and airplanes) because planes would literally fall from the sky. If large building design was as ad hoc as most software, the slightest wind would knock over the Empire State building.
While software development tools, best practices and methodologies have made huge leaps and bounds in the last 10 or 15 years, software still crashes. Software in theory, should run perfect as expected every time. Actually, software does run perfectly, all the time, the problem is software is written incorrectly and bugs are actually expected but unintentional side effects (hopefully).
Software crashes because of human error, either the developer underestimated an event or the end user carries out an action not anticipated by the developer. Unlike when an aircraft is built, software usually isn’t developed against any kind of blueprint (some methodologies actually do something very similar — but has been proven many times this isn’t cost effective) so developers begin writing code immediately. One line turns into 10, then 100 then a 1000 and a few months later you have a finished semi-working product.
This is why the software industry has BETA releases because developers can’t possibly catch all bugs during initial development. Imagine building an airplane without any planning or prior experience, only a working knowledge of basic electronics, flight and structural design. Chances are the plane wouldn’t fly, so every one would remain safe, but in software, crashing doesn’t kill you so users have become accustomed to less than perfect experiences.
Most software is not developed against any kind of standards document. While some developers might employ best practices they picked up over the years or read in a book (ie: design patterns) this is clearly not enough for high quality software. Post secondary institutions usually teach more implementation level programming (ie: advanced algorithms) as opposed to interface design, which is far more important to the overall architecture of the system and where standards exist but are rarely applied or fully understood.
Standards dictate everything in a software project, directly or indirectly. For example, if there is no minimum standard for lines per method, functions can grow to unbelievable lengths, becoming so verbose that even the original developers struggle to maintain the code. While bugs are almost exclusively the domain of implementation (not the interface) they are influenced by the interface, in that several smaller well named functions are much easier to add to, remove from or just change in general. One bug in a large function can make finding it and fixing it exponentially more difficult.
Software development is chaotic in nature, programmers running around in their own little heads trying to figure out how best to solve a problem, the whole time missing the big picture, because there isn’t one. Standards are important because they enforce best practices and good design that results in overall better software.
In short, I want my software to not only function as expected but also remain beautiful in source code form. It is difficult to take pride in something virtual like software when you have nothing to calibrate the results against (short of being impressed with a pretty front end design).
Setting and achieving high standards is more believable when you have quantifiable evidence, such as unit tests, XHTML validation, code convention validation, a solid architecture and application that doesn’t just fall over and die for no reason.
PCSpectraCategories
Archives
