Page 1 of 3

Warning Long!!! Suggested coding conventions document

Posted: Fri Aug 18, 2006 12:47 am
by alex.barylski
Ok, so i've spent the better half of today and yesterday considering coding conventions...

I've spent years tweaking mine so they fit and prevent issues and still some people want to call my ideas silly... :P

Anyways, there are some conventions which I follow religiously because they actually had a practical purpose, not just aesthetic...

I'm looking to change my conventions again and this time following more in the path of Zend framework, etc...

So here I am looking at the Zend framework...

http://framework.zend.com/wiki/display/ ... g+Standard

When I stumble across file names...they don't allow file names to have underscores, but instead use a CamelCase convention in naming files...

Years back I discovered an interesting nuance in Windows and Linux...I had in my HTML numerous links which pointed to my files like so:

<a href="somefile.html">Download something</a>

But the file, little did I know, had been displayed in the listbox for the FTP client in all lower case...when in fact, the file was actually first character capitalized...

Somefile.html

Locally, using Windows PWS, everything ran like a charm...but when I uploaded it to my web server, which was unix based, the links stopped working because files are usually case sensitive under unix... :P

I wasted a number of hours trying to figure out WTF was going on...

So from that day forward, I swore I would always use lowercase for all files, as it seemed to be the Linux fashion...and I would use spaces to seperate words...

Besides all caps looked ugly...and by allowing myself to use a single uppercase anywhere in a filename, either by accident and not noticing or indirectly by a typo...I was opening myself for a whole can of worms again, and when something chokes and it doesn't make sense...I never think clearly...and start looking at the weirdest things for answers...

So yes, I justied keeping all files lowercase and every reference to a file as lowercase...this way, by following convention...I would never make that mistake again...and guess what? I never did :P

So you can see how I would be hardpressed to change that now, some 6 or so years later...

Zend FW uses underscores in the class/interface names to indicate directory location, which is cool and makes sense, but this also makes it's impractical to have have spaces in the file names which contain the classes/interfaces and because they use camel case to seperate words, the chances of accidently doing what I did years ago, arises...

Strike one for Zend coding conventions...perhaps this is a mistake of a Windows developer switching to the world of Linux, but nonetheless, I feel my argument justified...

Zend also uses the prefix "Interface" on the interfaces you implement...

Coming from a C++ background, I always used CSomeClass or ISomeClass in my opinion, abbreviating anything while coding is a good idea...besides what if you actually need to use Interface as a descriptive name???

I suggest using the following prefixes:
C = Class
I = Interface

Underscores in class/interface names...not really needed as camelcase will suffice, however I typically liked to use a "_" at the end of a class name declaration followed by an acronym if required...

CTokenizer_HTML

This tells you:
1) It's a class, not an interface or template or a structure, etc
2) It's a tokenizer
3) Which tokenizes HTML

Clear, constructive, concise and informative...

The coding conventions for function names I appreciate as I've always done:

resetSomeThing() at least for member functions...

Global functions, I've always prefered to use lower case and seperate words with underscore, in the spirit of Linux... :P

This would typically help me distinguish between globals and locals, but in PHP and other scripting languages, you can use the 'this' pointer to distinguish that...

So I"m not sure that applies any more, same goes for prefixing variables with 'm_' to indicate member variables...

Although it does prevent you from accidently using a member, by redefining it inside your local function scope...so perhaps there is still some use to that madness???

As for Hungarian notation: http://intentsoft.com/technology/glossa ... #hungarian

It's not really needed is such high level languages as PHP or Javascript...so 'im not sure thats justified anymore...

I still personally like to use lowercase variable names with words seperated by underscore...maybe the linux influence???

Perhaps, locals should remain lowercase and globals camelcase???

I've always liked the idea of using the following convention...

Code: Select all

g_myGlobalVar
m_myMemberVar
a_myArgumentVar

local_var
Although, perhaps dropping the underscore and lowercase prefixing like:

Code: Select all

gGlobalVar
mMemberVar
aArgumentVar

local_var
Would yield more aesthetically pleasing results???

As for comments, I always use phpDocumentor as a standard...this area could use elaborating...but I'll save that for another day... :)

Variable initialization is something I try to do 100% of the time...even if it's zeroing...doesn't matter...

When more than one variable in a group of similar variables all require the same initialization value, I chain my initialization like so:

Code: Select all

$a = $b = $c = 0; // Initialize indicies to zero
Formatting 101

Here is where things become more about aesthetics then actual practicality...

Code: Select all

for($i=0; $i<$cnt; $i++){
  if($i==10)
    echo 'Eat my shorts';
  else{
    echo 'Jump over the moon';
    exit;
  }
}
Is how I've always coded...I use tabs, not spaces...but only in PHP and Javascript, because those extra characters add up in bytes as further lengthen your parsing times, etc...

I also use 2 spaces/tab so by using tabs I allow others to use 4, 6, etc...

I don't use curly braces around single statements, as it's not nessecary and saves some space...

Lines are a premium resource for me, I run at 800x600 so I only get at best 30 visible lines, less if all toolbars, etc are displayed...

For this reason, I like to keep curly braces tightly flush against it's previous token, ecept ending braces in which case, they always deserve their own line and depending on nesting levels...I sometimes comment what that curly brace is closing...

As for the issue about spacing between keywords like (for, if, while) and the brackets, etc...

Like done above, I don't use spaces, except to seperate expressions/statements...most coloring editors will allow you to color keywords differently than brackets and some will even color variables differently as well as numbers...the following are my settings:

Numbers as FUSCIA
Strings are RED
Comments are GREEN
Constants are ORANGE
Keywords are BLUE

These colors distinguish between keywords and expressions, just fine, and again...I don't waste space...which is important in PHP and scripting langauges...

What are your opinions about this? Do you prefer Zend style with the spaces?

Classes, Interfaces, etc...I always have the curly brace on the same line, but function braces get their own lines...

Comments, if more than a single line...I encapsulate between /* */ so editors which support source folding can minimize the comments, thus giving me back some valuable line space...

Multi-line comments, I always pro/preceed with a single white line, just for aesthetics...

Anyways, my hope is to drill out what works best for everyone and "why" and preferably come to a community decision and possibly get some standard we can all follow as a community...I'll modify my own standards to meet the suggestions of a community, assuming every reason is actually justified and not given "just because"...

What do you all think? Would you like to contribute to something like this? I personally say it's worth a shot...as I'd like to start using some of yours code in my projects and solid convention is always good...

We could begin work on single classes, write them according to convention and actually have useful code available to the community at large...

Eventually maybe building a devnetwork framework...??? :P

Anyways, just throwing ideas out there...all I need is a few more people, other than myself to make suggestions, assist in writing rough drafts, etc...

Eventually I'll have an updated polished version in PDF form available on my web site with a link to download in my sig...

Sounds good no???

Cheers :)


feyd | fixed the spelling in title.

Re: Wanring Long!!! Suggested coding conventions document

Posted: Fri Aug 18, 2006 1:42 am
by feyd
Hockey wrote:they don't allow file names to have underscores, but instead use a CamelCase convention in naming files...
I've never been a fan of underscores. However because my style is flexible, I can roll with it.
Hockey wrote:Zend FW uses underscores in the class/interface names to indicate directory location, which is cool and makes sense, but this also makes it's impractical to have have spaces in the file names which contain the classes/interfaces and because they use camel case to seperate words, the chances of accidently doing what I did years ago, arises...
spaces in filenames: big fat no.
Hockey wrote:Coming from a C++ background, I always used CSomeClass or ISomeClass in my opinion
I remember those fairly hungarian ideas from C. As I said before, I've moved on from that phase.
Hockey wrote:abbreviating anything while coding is a good idea
In my book, abbreviation should be avoided unless the result would be unwieldly long. When that happens, it may be time to come up with a different name, not abbreviated, different.
Hockey wrote:Underscores in class/interface names...not really needed as camelcase will suffice, however I typically liked to use a "_" at the end of a class name declaration followed by an acronym if required...
As before, I avoid underscores.
Hockey wrote:The coding conventions for function names I appreciate as I've always done:

resetSomeThing() at least for member functions...
My current "habit" is upper camelcase e.g. ResetSomeThing(); for methods. Global functions I use standard camelcase.
Hockey wrote:Global functions, I've always prefered to use lower case and seperate words with underscore, in the spirit of Linux... :P
You should know my answer here.
Hockey wrote:same goes for prefixing variables with 'm_' to indicate member variables...

Although it does prevent you from accidently using a member, by redefining it inside your local function scope...so perhaps there is still some use to that madness???
It's fairly obvious if you're redefining a property: $this->property or self::$property. Don't know about you, but that's hard to mix up with $property. ;)
Hockey wrote:As for Hungarian notation: http://intentsoft.com/technology/glossa ... #hungarian
Spewww. :)
Hockey wrote:It's not really needed is such high level languages as PHP or Javascript...so 'im not sure thats justified anymore...
Yep, it's largely useless these days.
Hockey wrote:I still personally like to use lowercase variable names with words seperated by underscore...maybe the linux influence???
Image
Hockey wrote:I've always liked the idea of using the following convention...

Code: Select all

g_myGlobalVar
m_myMemberVar
a_myArgumentVar

local_var
Although, perhaps dropping the underscore and lowercase prefixing like:

Code: Select all

gGlobalVar
mMemberVar
aArgumentVar

local_var
Would yield more aesthetically pleasing results???
Less underscore, good. Chicken, good.
Hockey wrote:As for comments, I always use phpDocumentor as a standard...this area could use elaborating...but I'll save that for another day... :)
Never really liked javaDoc/phpDocumentor/Doxygen syntax. I can roll with it, it just doesn't blow my skirt up, figuratively speaking.
Hockey wrote:Variable initialization is something I try to do 100% of the time...even if it's zeroing...doesn't matter...
It's good programming practice, avoids some security issues (especially register_globals related.)
Hockey wrote:When more than one variable in a group of similar variables all require the same initialization value, I chain my initialization like so:

Code: Select all

$a = $b = $c = 0; // Initialize indicies to zero
I do that on occasion, but more often than not it will be on the loop variables like you have there. i.e. 1-2 alphanumeric character variable names.
Hockey wrote:Here is where things become more about aesthetics then actual practicality...

Code: Select all

for($i=0; $i<$cnt; $i++){
  if($i==10)
    echo 'Eat my shorts';
  else{
    echo 'Jump over the moon';
    exit;
  }
}
Is how I've always coded...I use tabs, not spaces...but only in PHP and Javascript, because those extra characters add up in bytes as further lengthen your parsing times, etc...

I also use 2 spaces/tab so by using tabs I allow others to use 4, 6, etc...
tabs/space, doesn't matter to me as long as it's consistent.
Hockey wrote:I don't use curly braces around single statements, as it's not nessecary and saves some space...
I do, always.
Hockey wrote:Lines are a premium resource for me, I run at 800x600 so I only get at best 30 visible lines, less if all toolbars, etc are displayed...
2x 1920x1200 displays. Hundreds of lines. :) Even on a 800x600 I get 60-80 lines. My prompt window is 315x145 characters.
Hockey wrote:For this reason, I like to keep curly braces tightly flush against it's previous token
This convention stems from the older displays of few lines. I can understand it, but I don't personally like it. I like my braces lined up with their counterparts.
Hockey wrote:ecept ending braces in which case, they always deserve their own line and depending on nesting levels...
100% agree.
Hockey wrote:I sometimes comment what that curly brace is closing...
rarely, but sometimes I do as well.
Hockey wrote:As for the issue about spacing between keywords like (for, if, while) and the brackets, etc...

Like done above, I don't use spaces, except to seperate expressions/statements
I, like newspaper layout people and books, like whitespace.. lots of it.
Hockey wrote:I don't waste space...which is important in PHP and scripting langauges...
Less and less important as processor power goes higher and higher and techniques for parsing become better.
Hockey wrote:Comments, if more than a single line...I encapsulate between /* */ so editors which support source folding can minimize the comments, thus giving me back some valuable line space...
Comments of length get their own lines. Multi-line comments, doesn't matter to me if they're in C or C++ form.
Hockey wrote:Multi-line comments, I always pro/preceed with a single white line, just for aesthetics...
As before, I like whitespace. So I'll have two blank lines before a comment block, sometimes one after it too -- although rare.
Hockey wrote:What do you all think?
Honestly, I don't really care about coding conventions outside of corporate environments and within projects. The distinction for me is as long as there is a convention in the project, I'll follow it. I don't care what the specifics are. It just isn't so important to me.
Hockey wrote:We could begin work on single classes, write them according to convention and actually have useful code available to the community at large...

Eventually maybe building a devnetwork framework...??? :P
Already in process. 8O

Posted: Fri Aug 18, 2006 1:46 am
by RobertGonzalez
Dangnabbit, that is one long post. There are some things in that post that I can reply to, but not all (at the moment). Here are a few...

File names
I use to use underscores for all spaces in file names. Now I use hyphens. So before, where I would have had my_db_code.php I now have my-db-code.php. Don't know why, just personal preference I guess. I never use upper case letters in filenames. Ever.

I also do not name my files with the type of code in the file. I know this can cause problems, but I usually use descriptive file names so I can easily tell what is going on in the file.

Class names
I always start the class name of with an Upper case letter and I use underscores for spaces: My_db_class.

Function names
I never use upper case letters in function names and I always use underscores for spaces.

Variables
I usually try to be descriptive for vars that are used throughout a script. I usually try to tell what type of var it is, but at the end of the var name instead of the beginning: $my_user_array, $error_msg_string. The exceptions to this are integers and booleans, though with booleans I usually use is_something to let me know that the var will be either true or false.

Code syntax
I will almost always use bracketed code even if there is no call for it. I will always initiate my vars and set them to defaults if I know defaults. I will always use spaces between parantheses and I always use tabs instead of spaces for code outlines.

Code: Select all

<?php
$msg_string = '';
$is_error = false;
$error_array = arra();

if ( function_to_eval() )
{
    $msg_string = 'This is now set to message';
}
else
{
    $is_error = true;
}

if ( $is_error )
{
    if ( error_array_setter() )
    {
        while ( set_error_array() )
        {
            $error_array[] = set_error_value();
        }
    }
}
?>

Posted: Fri Aug 18, 2006 1:57 am
by s.dot
Can I feel a matter of personal debate coming on? :-P

I've tried camelcaps when naming variables. It just doesn't "feel" natural to me. Thus i've decided to stick with underscores and $long_variable_names. They're descriptive and spacious, meaning easy readability. With camelcaps you sometimes end up with letters that appear similar, like a lowercase L and a capital I.

For files, I never go with camelcaps. Rarely underscores. Usually just one word. Althought lately i've been hyphenating-some-pages.php. ;)

IMO, I don't see a point in changing the case/naming convention between local and global variables. What for? One more thing to remember and get used to.

As for aesthetically pleasing, you're right. You'll probably not get it 100% the way you like it on the first try. When I write code I know someone else is going to look at... I write it and then go back over it.

As for single ifs, I'm with feyd. I always use the brackets. Lately I've adjusted my habbit to drop the opening bracket to it's own line and having the closing bracket on it's own line. Sure, compacted code LOOKS nice, but it's not too swell to try to comprehend and look at at a glance.

As for comments, I generally go all // style. Unless there's a really long comment, then I put a * at the beginning of each line. It just makes it stand out more.

@feyd: devnetwork framework? 8O

[Edit] When working on a project with multiper coders, I think the coding and naming schemes should be specified and agreed upon at the beginning of the project. Perhaps even someone designated to make sure the code is consistent. I may not be at the point to say it yet.. but I think any good programmer would easily be able to adapt.

Posted: Fri Aug 18, 2006 2:09 am
by Christopher
I will simply register my standard complaint about discussions of coding conventions and get out of the way.

Posted: Fri Aug 18, 2006 3:25 am
by Oren
scottayy wrote:As for single ifs, I'm with feyd. I always use the brackets.
Me too, and my brackets get their own lines.

As for comments, I always use /* A comment here */ and if the comment takes more than one line I leave an empty line above and bellow the comment.
feyd wrote:spaces in filenames: big fat no.
Absolutely! Two reasons:

1. Just doesn't look good, and is not allowed according to my coding guidelines (all lower case with underscores).
2. In old PHP versions there was a problem with this when you tried to upload a file which had spaces in it.

Filenames, function names, class names, variables and generally all my code with few exceptions (see below): lowercase_with_underscores_for_spaces.

Exceptions:
1. My constants are uppercase.
2. When I want to get the error message, in order to make it easier to read I use:

Code: Select all

echo $e->getMessage();
Since this function is not my own defined function, I can't name it as get_message, and since readability is very important to me I use an uppercase letter for the first letter in each new word (but not in the first word).

This exception is only true with the getMessage(), getLine() and all the others which are used to get information about an exception... I don't use it with other functions, e.g I don't do:

Code: Select all

exif_imageType($filename);

Posted: Fri Aug 18, 2006 6:29 am
by Ollie Saunders
I follow Zend coding standards virtually to the word. The only thing I had reservations about was this

Code: Select all

// originial ole style
$a = array(
    'some long array value like this',
    'followed by another on a separate line',
    'and one last one there'
);

// ZF style
$a = array('some long array value like this',
           'followed by another on a separate line',
           'and one last one there');
But I've started using the ZF style now.

I particularly like to stress:

Code: Select all

mysql_query ($q); // what so mysql_query is a language construct now?
if($i == 4) // what so if is a function now?
so i prefer

Code: Select all

mysql_query($q);
if ($i == 4)
better :)

Here are some others of mine:

Code: Select all

Any language
    - Use the fewest number of names as possible, where ever you can reuse do this helps
      to make things more polymorphic, and its easier to remember.
    - Spell your names correctly!
    - Its worth giving thought to your names, if you think you are wasting time trying to
      think of one, do something else and come back. Don't use a poor name because you
      can't think of anything better! Get a thesaurus out if necessary, I routinely do.      
      If you use a bad one it'll be really annoying when you or someone else thinks of
      something better and you have to go back and change them all.

SQL Guide
    - use UPPERCASE for all SQL keywords
    - use `backticks` for all table and field names
    - write all foreign keys as ALTER TABLE `x` ADD CONSTRAINT at the end of a database structure file
    - TableNames in CamelCaps
    - fieldNames in alt camelCaps
    - _foreignKeyFields like normal field names only prefixed with an underscore
    - The primary key is always the same as table except that it is suffixed with 'Id' and observes alt campelCaps
    - Avoid triggers, stored procedures and views, they do nothing to reduce the work load and make 
      your database less portible
    - Use 0 and 1 rather than FALSE and TRUE for portibility, BOOLEAN column type is fine however because
      this only appears in the create table syntax.
    - Learn the rules of normalisation, follow them for a while. Once you are confident about creating
      database structures you can start to break the rules.

Posted: Fri Aug 18, 2006 6:53 am
by Jenk
For a while I followed PEAR's standard, but now just go with what I like.

At the moment, if it's a global scope entity, it is camelcaps with first letter cap'd:

Code: Select all

$var = SomeFunction();
If it's a member, or local scope (i.e. variable,) first char is lower:

Code: Select all

$someObject->someMethod();
Registry::getInstance();
braces: newline for opening brace on class and function/method definitions, and closing is always newline and vertically aligned with decalration title. Loops, if's and switches: opening brace on same line.

Code: Select all

class Foo
{
    public function __construct ()
    {
        $args = array();

        if (($num = func_num_args()) > 4) {
            
            for ($i = 0; $i < $num; $i++) {
                $args[] = func_get_arg($i);
            }
        }

        $this->bar = $args;
    }
}
also as you can also see, I keep a whitespace gap above and below brace blocks, with the exception of if the preceding/successing line is a brace.

Underscores are a no-no for me.

File names:

if it's a class file, it is exactly as the class name is, appened by 'class.php' (for autoload ease)
If it's anything else, such as a config file, it's all lowercase appended by 'inc.php'

Posted: Fri Aug 18, 2006 8:35 am
by jayshields
Well, I dont like capitals or underscores in variables at all, I simply don't like the shift key :D

To do with syntax, I think my style combines the best bits from everyones :)

Single statement if's don't get curly braces and it's all on one line, I only recently started doing this. One downside is that if you want to add an extra statement it's alot of messing about. For example:

Code: Select all

if($name == 'john') $error = TRUE;
would have to become

Code: Select all

if($name == 'john') {
  $error = TRUE;
  echo 'You\'re name shouldn\'t be John!';
}
Which is a large change. Also, my loops, while's, etc, all take the same structure as my if's, and I always use a tab (4 spaces), although on the forum I just use 2 spaces.

Another thing I recently started doing is not leaving spaces between the concatenation operator. I used to do:

Code: Select all

$b = 'goo' . 'gle';
but now I find it easier to read/understand

Code: Select all

$b = 'goo'.'gle';
I still stick by leaving spaces before/after all mathematical operators.

Code: Select all

$answer = 4*8+2-9;
just seems harder to comprehend than

Code: Select all

$answer = 4 * 8 + 2 - 9;
I noticed noone has mentioned the AND OR operators, seems everyone goes for the && and ||.

That's about all I can be bothered typng.

Image

Posted: Fri Aug 18, 2006 8:41 am
by Ollie Saunders

Code: Select all

if($name == 'john') $error = TRUE;
Pet Peeve: Did you define TRUE as a constant? TRUE is a throw back from C when there was no boolean type:

Code: Select all

#define TRUE 1
#define FALSE 0
Its not necessary these days because we have boolean type, true and false keywords. All other keywords are written lowercase (if, while, for, class etc.) why capitalize true and false?
I noticed noone has mentioned the AND OR operators, seems everyone goes for the && and ||
They aren't the same: viewtopic.php?t=53476 but generally i prefer "and" and "or" to "&&" and "||", just easier to read.

Posted: Fri Aug 18, 2006 9:28 am
by jayshields
I don't know why I capitalize true and false, I've always done it. I supposed now you say it it seems weird, since, as you mention, capitalization usually refers to a constant.

I'm taking the "did you define true as a constant" as sarcasm...?

Also, never realised && and AND / || and OR were different. I looked at the thread but I think you gave a poor example, I would never use a statement like that. Do you have an example where it could actually cause an error in a real situation? :P

Posted: Fri Aug 18, 2006 9:41 am
by Ollie Saunders
I'm taking the "did you define true as a constant" as sarcasm...?
Well it was just draw attention to the problem really.

Here's the example you asked for:

Code: Select all

$foo = 0;
$bar = 20;

$a = $foo or $bar;
var_dump($a); // int(0)
$b = $foo || $bar;
var_dump($b); // bool(true)

Posted: Fri Aug 18, 2006 9:48 am
by feyd
jayshields wrote:Do you have an example where it could actually cause an error in a real situation? :P
A grep from one of my source trees

Code: Select all

lib/Utility/class.Transform.php:26:             if (is_array($aInput) || is_string($aInput) and is_callable($aInput))
lib/Utility/class.Transform.php:53:             if (is_array($aOutput) || is_string($aOutput) and is_callable($aOutput))
tests/lib/Utility/test.IPAddress.php:127:               if ($c > 2 or $c == 2 && !preg_match('#^(?:12[0-8]|1[0-1][0-9]|[1-9][0-9]|[0-9])$#s', $pieces[1]))

Posted: Fri Aug 18, 2006 9:54 am
by Ollie Saunders
feyd wrote:

Code: Select all

if ($c > 2 or $c == 2 &&
Wow, that's confusing, i would never mix like that.

Posted: Fri Aug 18, 2006 9:59 am
by Ollie Saunders
Sorry to double post i just remebered a really important convention I have. I alreadys brace variable properties:

Code: Select all

$property = 'name';
$a->$property = 'ole'; // perfectly legal but not particularly obvious
$a->{$property} = 'ole'; // me like much better xD