Coding Standards

Before embarking on developing software for ClarkConnect, please read and review the following coding standards. Code conventions are important to developers for a number of reasons:

80% of the lifetime cost of a piece of software goes to maintenance.
Hardly any software is maintained for its whole life by the original author.
Code conventions improve the readability of the software.
People make fewer mistakes in consistent environments.

Always keep your code readable. Good code is readable code.

Formatting

4-space tab
Use stylesheet formatting, avoid tags like font, size, etc.
Add the following to the bottom of all PHP: // vim: syntax=php ts=4
HTML tags in lower case - e.g. <td>, not <TD>
Function and method calls should use the following spacing style:
```
  WebDialog($example1, $example2);
```

block statements should have the following indentation and bracket style:

  if ($leafs == "winstanleycup") {
         ... do something ...
  }

Do not use tab alignment for documentation, variables, data structures, etc. Use two single spaces instead.

   Bad Sytle
     @param  string      service       name of xinetd service
     @param  string      errmsg        error message
     @return void

   Good Sytle
     @param  string  service  name of xinetd service
     @param  string  errmsg  error message
     @return void

Comments

Yes, use comments please.
Use phpDocumentor for all source code.
See templates below and http://manual.phpdoc.org/

Copyright

All files should start with a copyright notice, e.g.:

   ///////////////////////////////////////////////////////////////////////////////
   //
   // Copyright 200x-200x Point Clark Networks.
   //
   ///////////////////////////////////////////////////////////////////////////////
   //
   // This program is free software; you can redistribute it and/or
   // modify it under the terms of the GNU General Public License
   // as published by the Free Software Foundation; either version 2
   // of the License, or (at your option) any later version.
   //
   // This program is distributed in the hope that it will be useful,
   // but WITHOUT ANY WARRANTY; without even the implied warranty of
   // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   // GNU General Public License for more details.
   //
   // You should have received a copy of the GNU General Public License
   // along with this program; if not, write to the Free Software
   // Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
   //
   ///////////////////////////////////////////////////////////////////////////////

Variable names

Variable names can make or break readable code. Having to search through source code for a poor variable name like "o" is not fun. Using meaningful and variable names makes everyone a happier camper.

Avoid excessive abbreviation
Minimum 3 characters
All lower case

	Which Do You Prefer?

Put your feet in another developer's shoes. One day, someone will have to maintain your source code. For variable names, which would you rather see:

- interface, netmask, gateway, ip
- if, nm, g, ip

Function/Method names

Capitalize the first letter of every word, e.g. GetSubjectTag
No all upper case abbreviations, e.g. getHtmlBody (not getHTMLBody)

Class names

Capitalize the first letter of every word, e.g. SoftwareUpdate
Pick a name that fits structure of the current API
No underscores.

Constants/Defines

Use all caps
Use single quotes around define (see examples below)
Separate each word by an underscore, e.g. APACHE_FILE_CFG
Use the following naming standard ClassName_Keyword_Name where keyword is:
- FILE - example: define('SQUID_FILE_CONFIG', "/etc/squid/squid.conf");
- PATH - example: define('SQUID_PATH_SPOOL', "/var/spool/squid");
- CMD - example: define('TIME_CMD_HWCLOCK', "/usr/bin/sudo /sbin/hwclock ");
- CONSTANT - example: define('SAMBA_CONSTANT_SECURITY_USER', "user");
- DEFAULT - example: define('POSTFIX_DEFAULT_MAX_MAILBOX_SIZE', 51200000);

Classes

All configuration variables should be accessed using action words (SetX, GetX, AddX, etc).
Use PHPdocumentor for every method