Coding Guidelines
Last Modified: February 21, 2003 07:02AM
|
|
(Any)
|
Description
This is the Mantis coding conventions document. This should assist anyone who wants to modify the code or work on active development. Anyone who wishes to contribute code must adhere to these guidelines. Code not following these conventions will be modified or (in extreme cases) rejected. If you have additional suggestions or a good argument for changing some of these guidelines then send a message or post in the forums.
First, start off by reading the PHP Coding Standards document. I've deviated in a few places but just about everything in the document applies here as well.
Above all, write code that is easy to read and maintain. Comment blocks of code and functions at all times. And get on my case if I deviate too much as well!
Naming Variables
Use all lower case.
Use _ to separate words. eg. $green_color_value
Use descriptive names (exception for loop variables).
Loop variables can be of the usual variety: $i, $j, $k, etc.
Count variables should append _count. eg. $bug_count
Global variables should be prefixed with g_
Function parameter variables should be prefixed with p_
Variables passed from forms should be prefixed with f_
Temporary variables should be prefixed with t_
History logging variables should be prefixed with h_
Other variables are prefixed with v_, v2_, etc
Never prefix with l_ or o_ or q_ (visually confusing)
$query and $result should be used for SQL query and results respectively
Naming Functions
Use all lower case.
Use _ to separate words. eg. setup_page_breaks()
Keep functions to 5 words or less
Functions that print should be prefixed with print_.
Try to use prefixes to group functions (i.e., email_, news_, etc)
Naming Classes
Use FirstLetterOfWordIsCaptilized style
Variables that are class objects should have the prefix coo_
Naming Files
Use all lower case.
Use _ to separate words. eg. view_new_bugs_page.php
Use .php file extensions (previously we used .php or .php3)
Filenames must be less than 32 characters in length. This plays nice with older file systems like MacOS.
Included files should be suffixed by _inc.php
SQL formatting
UPPERCASE all SQL keywords:
$query = "SELECT * ".
"FROM $g_mantis_bug_table ".
"WHERE id='1'";
Always assign a query string to a variable. This makes code easier to debug when problems occur. Do not create the query in the call to the function.
Break up SQL queries over multiple lines to be easy to read.
General Formatting
Use TABS with a size of 4 to make the code easily readable while not wasting too much space
Follow the table formatting of existing pages
Always use long php tags( <?php ). No short tags ( <? ).
Try not to print/echo HTML unless it's short or in a function loop
Do not use the EOF construct.
Miscellaneous
Don't use the ternary (?:) construct. It is confusing and has too much bug potential. The only exception is when checking if a variable has been initialized.
Avoid magic numbers. The only magic numbers in use should be 1 and 0.
Page Guidelines
The first item should be the copyright notice
Followed by CVS header
The next line should be a cookie check to see if the user is logged in
Next should be the majority of the SQL queries for a page
Start of compression (if needed)
Next will be the various thymol print_ functions.
The main body of the page will follow
At the bottom will be the footer information and closing print_ functions.
End of compression (if started)
Braces and Paranthesis
Paranthesis should be right after a function name. eg: function() not function ()
Paranthesis should have a space right after a keyword (if, while, for) eg: for (...)
Braces formatting is illustrating below. I don't mind the macthing vertical placement myself but in the interests of conserving some space I have adopted the unmatched placing.
for ( ... ) {
blah
}
or
if ( ... ) {
blah
}
if ... else blocks should be in this format:
if ( ... ) {
blah1
} else {
blah2
}
Comments
Use the # symbol for line commenting
Use /* */ for block commenting unless you nest /* */ comments. Generally, only use this during development.
Use @@@ followed by a brief message (BROKEN, TEMPORARY, etc) as a look at this indicator. Leaving your name next to it might be a good idea as well. This way critical items can easily be found.
Editor Features
Search and replace in multiple files
Goto line number
Syntax highlighting
Adjustable TAB spacing
Contributing Patches
It is recommended that you discuss what you are planning to do with the developers before starting (specially if the change involved database format changes). This increases the probability of your patch being applied.
Think generic! Only generic features that server the majority of the users will be included into Mantis.
Use "cvs diff -u" to generate the patches.
To speed up the process of applying patches, apply and test your changes on the CVS HEAD.
Send your patch to mantisbt-dev@lists.sourceforge.net. Make sure to include with the patch explanation of what exactly does the patch do.
Some email clients mess up attached text files, hence, it is recommended to also attach a zip version of the diff, or place it somewhere where the developers can download it. |
User Contributed Notes
Coding Guidelines |
|
mantisbugtracker.com@sebastianmendel.de
30-Oct-2006 7:05 |
#1283
|
this coding standards seem to be very outdated, even the original coding standards you refer does not exists any more
f.e. using tabs instead of spaces makes more trouble than benefit
it is a horror to supply patches following your coding standard ... |
|
|
|
| Last updated: Fri, 05 Sep 2008 - 15:45:16 |
|
|
