Warning Long!!! Suggested coding conventions document
Posted: Fri Aug 18, 2006 12:47 am
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...
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...
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
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...
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...
Although, perhaps dropping the underscore and lowercase prefixing like:
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:
Formatting 101
Here is where things become more about aesthetics then actual practicality...
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...???
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.
I've spent years tweaking mine so they fit and prevent issues and still some people want to call my ideas silly...
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...
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
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...
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_varCode: Select all
gGlobalVar
mMemberVar
aArgumentVar
local_varAs 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 zeroHere 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;
}
}
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...???
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.

