Coding Etiquette 101: 6 Obvious & Overlooked Best Practices

These are a few things that I’d thought were common sense when it comes to working on projects with other developers. Let’s call this Programming Etiquette 101.

1. Document Your Code.

This is the most obvious item, and the one that nobody likes to do. It seems like a waste of time, but taking a few seconds to explicitly say what everything does will save everyone time and headaches in the long run. What seems intuitive now can take a few minutes to interpret down the road, depending on stylistic differences and familiarity with the system. Your documentation could save someone an hour or two of digging through code a few months down the line.

Being able to tell what something does, in plain english (or whatever your project’s common language), with only a glance, saves time and keeps frustration down. It’s just good business.

1.5. No, Seriously, Document Your Code.

Using TextMate? “doc” above a PHP function will add a DocBlock. There’s probably a similar shortcut for practically every IDE.

Releasing a framework or library to the public? Please, please provide docs. Even just in code. Nobody wants to dissect the whole system every time a simple task arises.

2. Use Descriptive Variable Names.

$product_discounts > $pDiscounts > $pd

It all gets compiled into a symbol table anyway. Use variable names that clearly describe their purpose and contents. This is the cheapest and most effective documentation you can do. Take a look at this:

// get the discounts for each product
foreach($product_list as $product_id) {
  $product_discounts[] = $discount_model->get_discounts_for($product_id);
}

While it may not be optimal, it still makes the point. Reads nicely, right? Now try this:

foreach($plist as $p) $pd[]=$dm->dFor($p);

Does it take less time to type? Sure.

Will it make your current and future co-developers very unhappy? Yup.

Don’t do it.

The same goes for function names. If you find yourself documenting a function with “Does what it says on the tin,” you’re doing it right (you should still document the parameter(s) and return value(s), of course).

3. Follow the Conventions of the System

This is a short one. If you’re working in an MVC environment, don’t put a few hundred lines of controller logic in the view. Don’t put model logic in the controller OR the view.

Generally if things are structured a certain way, keep them that way, unless you have a very convincing reason to do otherwise (and if you do, document it).

4. Refactor Repetitive Code

I once knew a professor who said (paraphrased) “If your function is longer than ten lines, you should split it up.” I’m not going to advocate that kind of strict line count rule, but at least follow this simple one:

If you find yourself cutting and pasting code, consider making it a function. The same goes for if a particular set of tasks can be described by a function.

Here’s an example:

$this->collection[] = $this->load->something(‘first’);
$this->collection[] = $this->load->something(‘second’);
$this->collection[] = $this->load->something(‘third’);
$this->collection[] = $this->load->something(‘fourth’);
// and so on…

Inline rewrite:

foreach(array(‘first’,’second’,’third’,’fourth’) as $thing)
  $this->collection[] = $this->load->something($thing);

Function rewrite (generic):

// if you have access to $registry from this scope you don’t need it…
function load_things(&$registry, $thing_array) {
  foreach($thing_array as $thing)
    $registry->collection[] = $registry->load->something($thing);
}

load_things($this, array(‘first’,’second’,’third’,’fourth’));

Of course, if you have hundreds of items in there, you’d either have to type them all out or make some optimizations. Which leads me to…

5. Multiple Lines are OK!

Break up the following over multiple lines if your language allows it: Strings, arrays, SQL statements, and long function calls.

Take the following SQL for example: It’s pretty short now, but if there were a few more joins and constraints, it’d be a nightmare to maintain on one line.

// This is completely valid in PHP. Using {} interpolation is a personal preference.
$prefix = DB_PREFIX;
$sql = “SELECT * FROM {$prefix}things AS t
   LEFT JOIN {$prefix}other_things AS ot ON t.id = ot.id
   WHERE t.id = ‘{$this->db->escape($id)}’
   LIMIT 0, 100”;

In the case of long function calls, consider using an associative array (or dictionary) to pass in extra parameters. They have the added benefit of naming what they’re passing. Example:

do_something(“things”, 2, 455, 299, 200, 349); // no meaning without looking up docs

…versus…

do_something(“things”, array(
  ‘x_offset’ => 2,
  ‘y_offset’ => 455,
  ‘x_skew’ => 299,
  ‘y_skew’ => 200,
  ‘whatever’ => 349
)); // meaning is clear!

The more you can do to make things clear, the better. Nobody likes scrolling through a concatenated string 1000+ characters long on only one line.

6. Pick Common Conventions

Choose some well-thought-out conventions for your project(s) and have everyone stick to them. Even something as simple as standardizing tab widths and types will save some serious headaches. Take CodeIgniter’s style guide for example: Probably a bit overkill in some cases (OR versus ||, for example), but it has some great ideas, and it keeps things readable across the project.