When to commit

One of the first distinguishing signs is what they commit – is the version management system used as a backup tool or as a version tracking tool. Some seem to think, you should end the day by committing all your sourcecode (no matter which state it’s in). This is really bad sign. Others commit whenever a new file is finished and thought ready to use – which is slightly better. Others again commit once – just before a new release – and has the commit contain each and every change since last release.

In my world a commit should contain a complete new feature across all the files changed to make the new feature. The commit should preferably only address one change (a new functionality or a changed feature).

The commit message

Another way to spot bad habits is in the commit message. Is there a commit message at all? – if not, it’s a bad sign. Almost as bad are meaningless comments, which may come in all sort of varieties – “work in progress”, “bugfix”, “update”, “foobar”. I’m sure they make sense to the developer at the time of committing them, but hardly 6 months later, when browsing the logs and wondering why a certain change was made.

A less common bad commit habit is the “book style” – where the comment either contain a delta of the changed lines (literally or as a description) or the length of the comment is a small story explaining the reason for the change, why it was made the way it was and on and on.

I’d any day prefer seeing a reference to a bug/ feature tracking system (bugzilla, trac or anything like it), and a brief summary of the change in a 140 characters a less.

1. Spend time on the data model

Too often a data model is driven by code, not careful thinking, and this often causes problems has the web application develops and expand over time. When developing a site, which needs data stored in a database (as most web applications tend to do), do try to spend some time on the data model – which tables do you need, what fields should the tables have, are the naming logical and consistent, what constraints and limitations does the data model offer.

It’s often far easier to refactor code and functionality than it is changing the database tables and fields, and it can be a tremendous help while maintaining an application if you clearly understands the data its working with.

2. Get the basics working first and fast

It often takes a while to get a complete web application finished. Help motivating yourself by getting the core working first and then add features and frosting once it’s working. By having a working skeleton, I usually find it much easier guess how much work needs to finish the various features than I do guessing the work needed to complete a section (ie. admin interface) on the application.

3. Think performance and security from the beginning

Remember to think of performance and security from the very beginning. Sometimes performance – or security – may cause you to layout the data model in a certain way or structure the application a certain way. While you may be able to add performance and security during refactoring, it’s often much harder than it is keeping both in mind from the very beginning.

4. Don’t fix the future; focus on the current needs

I don’t care about the next version. I really don’t want an infrastructure in place, which can help me build the future versions of the application. I want the features and infrastructure in place for the current version I’m working on – and frankly the features in the next version has a tendency to change before I’m ready to develop them.
Too often future-proofing an application clutters the code and too often the clutter doesn’t ever come to any good use – it’s just noise once we get to the real future features of the application.

5. Naming matters

Do think of what names you use on functions, classes, variables and database tables through out the application – and choose something meaningful. A variable named $x doesn’t hint what it’s used for. Help yourself (and other looking at the code) by hinting the uses of various things by choosing meaningful names.

One of the nice examples of this, was a story called “5 tips and tools to develop php applications fast”, and while it may apply to the web applications developed by the author, it’s one of those where I question who is supposed to be the audience. All 5 tips are often found in many textbooks and other stories on the net, and in my experience they are all wrong (more or less naturally).

1) Use a MVC framework – it’s an industry accepted standard.
MVC as an idea may be accepted, but there are many ways of implementing the MVC – even with the various PHP frameworks. If you know the MVC pattern it may be an idea to look at the frameworks supporting it, but don’t get carried away.

• If all your old code is non-MVC code and you don’t have any plans to MVC-refactor it, it may cause you maintenance overhead to try a completely different style  on a single project/web application.
• If you aren’t used to using a (MVC) framework you need to invest time in learning it.

Do keep an eye on the overhead caused by the framework. If you web application has a heavy load and the framework causes 5-10% overhead, it may a bad idea.

2) Ajax Frameworks
Great idea.. but to utilize the power of an ajax framework, you need to learn how to use it. Also Ajax isn’t the holy grail of the internet. Sometimes it’s cleaver to use it, other times it isn’t. By using plain old HTML and reloading the page from time to time, it may be easier to debug the application.

Do also notice, that writing great/professional quality Javascript often requires just as great skills as writing professional PHP.

3) IDEs
An IDE – Integrated Development Environment – can be a great idea if you know your way around it, and use it regularly. An IDE is – like any other tool – something you need to invest time and resources into, if you want something back – and especially if we’re talking a beast like Eclipse-based tools.

4) Database creation/management software
Let me skip comments on database creating management tools. I’ve never really used them and don’t know if they’re a pain or a benefit. I have often seen though, that too easy access to the database, leads to sloppy database design (or at least something, that isn’t thought through).

So far it’s been my experience, that people who knows the command-line clients to databases, often has invested much more time in thinking their data models through and often spend a little more time considering the table layout, the field definitions, indexes and other important aspects, than those who use a nice graphical interface.

5) Object Relational Mapping
Object-Oriented programming isn’t a holy grail, and most people doing OO programming (in my experience) doesn’t genuinely do object-oriented programming – instead they use the OO-facilities in the language to slap functions together in a class.

There’s nothing wrong with procedural programming as such, and trying to force object-orientation into your code – and even abstracting it away through Object-relational mapping, has often lead to slow performance and odd database designs. If you know what you’re doing great, but there’s no free lunch, and trying to utilze ORM without having a pretty solid grip on what’s happening and why, rarely does anything good to your productivity.

I’m quite sure for some developers, using some sort of object-relational mapping might be a gain in programmer productivity, but do keep in mind, that if you’re developing a site with massive traffic, the programmer gains may easily be crushed in added server resource requirements – spending a few minutes extra optimizing and tuning applications, may in some cases save hours and hours of cpu cycles once the solution is deployed.

Getting back to the article, I’m sure the advise is well-meant and thought through by the author, but do always – as with all advise – think it through and see how may apply to your adoptation. In may daily development some of it is quite terrible (as I often work on a site with thousands if not millions of pageviews every week).

I’m wondering what my 5 tips would be for developing PHP applications fast would be. Check back in a few days, and there may be an answer – which may or may not – apply to you.

Proper and sane variable- and function names pays off instantly. Incredibly short or misguiding function and variable names doesn’t. While it may be fun naming functions “doMagic” or likewise, chances that you – or someone else maintaining the code years after will probably not appreciate it at all.

Reasonable commenting on functions and tricky code parts often come to good use, but too much commenting is distracting. Some is good, and less is often more valuable.

Version control logs can be quite valuable, if they’re descriptive for the change made. Too often though, was the comment “misc. bug fixing”, “problem solved” or something which years later was of no use or value at all.

Documentation kept apart from the source code seem to have none or very little value. Not once have I bothered to look in the wiki-documents or any other documentation which was in the code. In the few instances I did, minor changes and bug fixes had changed the code to such an extend (while not updating the documentation) that it was misleading at best.

The only cases where the documentation apart seem to make a positive is database diagrams and descriptions. They do seem to have value.

First make things readable.

While your brain may be wired to a system of only using single character variable and function names or naming global variables after your cats, no one else will get the system. Try to make all names as logical as you possible can. Making it easy to read the code – not only as syntax but also in the names used in classes, functions and other objects in your source, improves the likelihood that someone else can figure out what’s going on and inherit the code someday.

Second make the code do what it supposed to.

Sure it may be cool making the system a generic all-purpose Swiss army knife of software, but preparing the code for all sorts of functions with aren’t used and aren’t needed, it only cause confusion of the next developer trying to move your code forward. Objects and class hierarchies may be suitable in some cases, but sometimes it’s more wrapping and declarations than actual code – and you’re probably on a wrong path.

Third provide in-line documentation.

Documentation are like a ghosts – it probably doesn’t exist. Making pages of documentation is probably a neat way to spend time if your on billable hours, but if you’re a regular developer, documentation is – at best a necessary evil. Do try to provide brief relevant comments, when something complicated or “not too obvious” happens in the code. Don’t place small novels in the source, but short precise guidelines.

While the above tips doesn’t guarantee your freedom to move on to new exciting projects, it surely improves the odds dramatically when you code is inheritable and accessible by another developer.