[FAQ] Code Writing Conventions

[mdshare]

The following is intended to outline some common conventions used by programmers to enhance both the readability and understandablity of code. If you've been referred to this page its likely because *someone* couldn't read what the hell you were posting! Please take the following to heart, as its information that will save us and you headaches.

Take for instance the following block of sloppy, unreadable code:

 

if ( ! $_POST['submit'] )
  showform();
else {
mysql_connect("localhost", "...", "...") or die("Could not connect to database.");
mysql_select_db("...") or die("Could not use database");
$query = "select id from referee where id=" . $_POST['id'];
$result = mysql_query($query) or die("Error in the query: $query");
if (mysql_num_rows($result) == 0) {
  echo("<font color='#FF0000'>Invalid Login</font>");
  showform();
}
else {
  echo("<font color='#FFFFFF'>Logged In</font>");
  if ( ! $_POST['submitted'] ) {
    login(); ?>
    <form action="index.php" TARGET="_top" method="post">
    <input type="submit" name="submitted" value="Logout">
    </form>
  <?php
  }
  else
    logout();
}
}

 

This is a real user-submitted snippet of code BTW, if you're sitting there thinking to yourself; WTF? You're not the only one. Deviations from HTML standards not-with-standing, posting a mess like this makes it difficult for us to answer your questions quickly and easily.

Here's the same code written for the PEAR convention by Richard York, for the sake of completeness he has also adjusted non-standard HTML and enhanced the logic using isset() and empty():

 

if (!isset($_POST['submit'])) {

  showform();

} else {

   mysql_connect('localhost', '...', '...') or die('Could not connect to database.');
   mysql_select_db('...') or die('Could not use database');

   $query = "SELECT `field` FROM `table` WHERE `id`=". $_POST['id'];
   $result = mysql_query($query) or die('Error in the query: '.mysql_error());

   if (mysql_num_rows($result) == 0) {

       echo "<span style=\"color: red;\">Invalid Login</span>
\n";
       showform();

   } else {

       echo "<span style=\"color: white;\">Logged In</span>
\n";

       if (!isset($_POST['submitted']) || empty($_POST['submitted'])) {

           login();

           echo "
           <form action=\"index.php\" TARGET=\"_top\" method=\"post\">
                <input type=\"submit\" name=\"submitted\" value=\"Logout\" />
           </form>\n";

       } else {

           logout();
       }
   }
}

 

You can find the full PHP PEAR Group's coding convention documented here:

http://pear.php.net/manual/en/standards.php

And then the other popular method, and Richards personal favorite, is the one true brace convention:

 

if (!isset($_POST['submit']))
{
  showform();
}
else
{
   mysql_connect('localhost', '...', '...') or die('Could not connect to database.');
   mysql_select_db('...') or die('Could not use database');

   $query = "SELECT `field` FROM `table` WHERE `id`=". $_POST['id'];
   $result = mysql_query($query) or die('Error in the query: '.mysql_error());

   if (mysql_num_rows($result) == 0)
   {
       echo "<span style=\"color: red;\">Invalid Login</span>
\n";
       showform();
   }
   else
   {
       echo "<span style=\"color: white;\">Logged In</span>
\n";

       if (!isset($_POST['submitted']) || empty($_POST['submitted']))
       {
           login();

           echo "
           <form action=\"index.php\" TARGET=\"_top\" method=\"post\">
                <input type=\"submit\" name=\"submitted\" value=\"Logout\" />
           </form>\n";
       }
       else
       {
           logout();
       }
   }
}

 

Can you see why we're much more likely to respond to people who post code that is indented and easy to read? We're all busy folks, and no one wants to take the time to reformat your code just so it can be read. Personally, I would also avoid opening and closing PHP blocks, IMO, that just clutters the code more.