Date: 12 May 2010 Comments: 0

As many opinions as many people. I don’t want to talk here about which coding style is good and which is bad. I’ll tell you what coding habits are good for team development and what are not. If you look at the code of someone you can tell a lot from it. Mainly whether author is lone wolf or team player. Once again team player is what most companies are looking for, larger projects are done by teams not by individuals.

Code indentation – must have in all technologies. For PHP I recommend for  one level 2 spaces (better not tabs as these are represented differently in different editors or viewers. Set up your editor to insert spaces when tab key is hit. If you want to use tabs, then use tabs only. The worst is mixture of tabs and spaces).

Variable and structures naming – Same important  for being able to read the code at all as code indentation is also naming of variables. Variables and functions named in style “a” “b” “c” are very difficult to “decode” by human. If you want someone else to be able to read code after you better give meaningful names. Don’t be afraid of giving longer names, development tools provides you by name completions so you don’t  have to type if every time. The important point is to be able to judge what data a variable holds or similarly what a function with such name does.

Wrong, is this code getting a kitty by ID tag ;o) ?

$obj = new cat();
$res = $obj->get($id);

Correct

$category = new category();
$category_data = $category->get_data_by_id($category_id);

Block commenting – This is one of the most important teamwork coding element and is probably most omitted by programmers. Why is this so important? We talk here about larger projects which are object oriented and are developed in team. Development IDE you use is analyzing the code and gives you suggestions and help windows. It relies on commentaries a lot. Gives you description of what function is used for, what parameters it takes and also it often relies on return type from the function for further suggestions on return variable. If you use all this, coding becomes smooth and easy even across code you didn’t write yourself.
Also when code is good commented documentation generated by automated tools is not just bunch of objects and methods but it starts to look serious and useful. Look at c++ or Java style commenting both are being used in PHP projects.

Inline coments – these are at least same important as block comments. It makes clear what particular part of the code is doing and mainly why it is doing it. This many times saves a lot of time someone even the author of the code itself when reading it later. You don’t have to use excessive commenting of this type, just put it where it is useful. Consider this example, it shows bad in-line comment and good in-line comment.

Bad, this is classic example of comment that tells you what the code does. You are programmer you can see it does this so what’s the point of saying it again.

if (!empty($_REQUEST['login']))
  $auth->logout(); //log out if login is requested
$auth->start();

Good, this tells you why the code does what it does.

if (!empty($_REQUEST['login']))
  //we need this because user may be logged in with different user and may not log out before re-login,
  //system would not log in the other user if old is not logged out.
  $auth->logout();
$auth->start();

Don’t forget to use in-line comments not only in PHP but also in HTML and SQL queries.

SQL queries formatting – Yes, database is part of possibly all projects. This is also included in code and written by programmers so we need to be able to read it and understand as quickly as possible.

Suggestions here are

• make all SQL syntax keywords capital letters, it makes it easy to distinguish from column or table names and values.
• if the SQL is simple one line query, keep it that way, in one single line.
• if SQL is complicated, break it to several lines and use indentation to make it clear. Simple rule is to put break line after each SQL keyword. check examples below

simple

$sql = “SELECT id, name FROM item WHERE id = ‘$item_id’”;

complex

$sql = "SELECT
  *
FROM
  $this->tb_item a
JOIN
  $this->tb_item_attributes b
ON
  a.id=b.item_id
WHERE
  a.id=$item_id AND
  a.status IN (1,2) AND
  (
    a.price > $min_price OR
    a.price_coverted > $min_price
  )
ORDER BY
  a.date_added DESC";

That’s possibly all, as I said it doesn’t matter if you are used to put open curly bracket at the end of statement line or at the beginning of next line to open a block, or whether you use C++ or Java commenting style, such things are different from company to company, from project to project, you can adapt easily to these. What is more important you should get into making good readable code as soon as possible and this is achieved only by getting good habits in formatting, naming and commenting of code. This is part of being team developer.

Published by Stan Kuhn in: >Web developement PHP tutorial