Downhiller - 11:30 am on Sep 20, 2006 (gmt 0)

Some good rules of the road when coding that I like to stick by are:

* Try to write code that does not need alot of comments (good var names, indentation, function names, consistant styles, etc.).

* Use comments where it makes sense too. Using a two line comment to explain a 15 line function is better than having someone trawl the code trying to work out what it does. Also if you've done something "strange" explain why, you'll be glad you had when you return to it in 6 months time.

* Stripping out comments for speed gains is pretty serious and clutching at straws, reminds me of the old tips about removing the desktop image from you windows machine to make it go faster. If you have to go to the lengths of doing that then its time to upgrade.

* Show your workings, if you have used some code from another site leave us a link to the page in a comment so we can follow it up should we need to. Got some horrid business logic, tell us who came up with it in a comment or include some of the discussion or a human readable version of the logic, it all helps get our heads around it easier.

* Write for ease of code maintenance rather than the tightest possible code. Server time is cheap, coders time ain't. Don't make us dig around in hard to read code any more than we have to.

* Don't worry too much about showing off your coding skills by trying to compact everything into a one line wonder. Breaking it down and make it easier to read and debug will be more appreciated by those that follow you.

* Break larger functions down into smaller more targetted functions. A function should do one job well. Then you can use several functions to perform what you want knowing that they should all do their thing well, better to debug a 5 line functions that manages Capitalisation for instance than having a 100 line beast that trims, caps, html encodes, replaces, upper cases (but only on Mondays), etc. and having to step through it.

* Don't be affraid to have a function fail and bring a program to a halt. It will help with debugging. Having a function try to guess at what it should return can lead to problem further down the line as it returns a default value/object which another function is not expecting.

* Don't Repeat Yourself (DRY). Don't have multiple copies of the same function through out a project it can lead to you missing one when you have to change the code and ending up with some odd results. Move functions like this to just one place then there is only one place to edit it site wide.

* Write re-useable tests. Unit Tests as they are called are a gift from heaven. Automated tests that you can run again and again. So that when you do make a change you can run all the tests you have for your project and make sure they all pass (ie they all return an expected value, so with the Capitalisation function mentioned before you could pass it "the cat in the hat" and compare the returned result with "The Cat In The Hat".

* Have your functions return a usable string/object rather than writing the result out to screen from within the function. It makes them more usable as you can then chain functions together.

* Optimise when you need to, not ahead of time. No point spending a week honing a loop down to be lightening fast if the page its on only gets 3 hits a week and it does nothing heavy. Of course there are exceptions. Googles homepage does not use quote around its attribute although it should, but little tweaks like that to them amount to huge saving in bandwidth, an optimisation that was needed there and then.

* Clean up your mess. Don't leave lots of lines of debug code lying around the place, nothing worst than coming to a script 6 months later to find 100 lines of commented out code, whats it there for? Is it important? Should I leave it? Who knows! Clean it up.

* Use Source control. To avoid the last problem above start using a source control system (Subversion is free and easy to use and theres a book on how to use it). Then you can keep a track of all your changes rather than having to have index1.asp, index2.asp, index_backup.asp, index_old.asp lying around everywhere (come on, we've all done it). If you need to roll back to a previous version you can.

* Back it up. You know it makes sense. You can even back up your source control system.

* Test you back ups. Can you get the data you need out of a back up? If not whats the point in having them?

Pete