Coding conventions

Ye' old general discussion board. Basically, for everything that isn't covered elsewhere. Come here to shoot the breeze, shoot your mouth off, or whatever suits your fancy.
This forum is not for asking programming related questions.

Moderator: General Moderators

alex.barylski
DevNet Evangelist
Posts: 6267
Joined: Tue Dec 21, 2004 5:00 pm
Location: Winnipeg

Coding conventions

Post by alex.barylski »

So I decided that I am going to sit down and write a formal document explaining how and why I use certain conventions when writing PHP code.

For reference and ideas, I'm curious...

What standards, conventions, etc do you use when writing code.

Having come from C/C++ I use hungarian style notation, but I also am starting to use a Linux style when writing procedural...I can't explain why exactly, just that it's rubbing off on me now that I've gotten away from Windows development using MFC.

I do however name my classes, methods and members as I did in C++...

For me personally, I find that by having different styles for classes, methods, functions, etc...it almost further helps organize my source...if I look at a function (besides the obvious using -> or ::) I can immediately determine it's a method or a global function, which I find makes it "stick" out that much more, like adding colorizing to editors helps comments stick out almost. So I justify my convention in that regard.

So, what techniques, etc do you use to make code more readble, structured, etc...?

Do you use Camelcase or whatever it's called? Java's style?

If you can, please explain why with an answer...

I'm NOT looking for a "read this document it explains what you are after"...I'm just as tech savvy as you are and I know how to use Google too... ;)

I'm looking for personal opinions, etc...

For instance, I personally don't use this technique, but:

Code: Select all

if(0 == $a)
Some people like this as it gaurantees you cannot accidently use assignment operator instead of comparison, which some people obviously have problems with...

I for one, can say I have honestly never made that error in either C/C++ or any other language which provides a different operator for comparison and assignment.

Anyways, that is a technique or coding convention which is easily justified because it's answer is obvious and it does serve it's purpose, just not for me.

This is ideally what i'm looking for...

So please, if someone has already answered with I use CAMELCASE because...

and your answer is the same, there isn't really a need to answer...or reply to this topic...

You get my idea :)

Cheers :)
User avatar
feyd
Neighborhood Spidermoddy
Posts: 31559
Joined: Mon Mar 29, 2004 3:24 pm
Location: Bothell, Washington, USA

Post by feyd »

Lets see, I used to do hungarian in C, but changed when moving to C++ to more descriptive names, less emphasis on what type it holds since most of my stuff was custom types with their own handlers anyways. So now, I use camelcase for variables with a leading lowercase letter. Methods and functions are camelcase as well, but with a leading uppercase letter. Arguments to methods and functions start with 'a' to denote an argument. Personally, I don't like hitting underscore. Other than the finger pattern shifting away from home position, I can't really explain why (although it does require more typing..)

If working on a class that could have namespace issues -- often what class doesn't? -- I will prefix the classname to help separate it and give the classes a unified namespace. There's still potential for namespace collision, but it's less than without the prefix. :)
alex.barylski
DevNet Evangelist
Posts: 6267
Joined: Tue Dec 21, 2004 5:00 pm
Location: Winnipeg

Post by alex.barylski »

feyd wrote:Lets see, I used to do hungarian in C, but changed when moving to C++ to more descriptive names, less emphasis on what type it holds since most of my stuff was custom types with their own handlers anyways. So now, I use camelcase for variables with a leading lowercase letter. Methods and functions are camelcase as well, but with a leading uppercase letter. Arguments to methods and functions start with 'a' to denote an argument. Personally, I don't like hitting underscore. Other than the finger pattern shifting away from home position, I can't really explain why (although it does require more typing..)

If working on a class that could have namespace issues -- often what class doesn't? -- I will prefix the classname to help separate it and give the classes a unified namespace. There's still potential for namespace collision, but it's less than without the prefix. :)
I use underscore more and more these days, but never even considered breaking typing patterns, which is a reasonable argument... :)

I do that all the time :)

Usually with the name I've given my personal library :P

Hmmm...anyways, thanks for the input...I'll have to consider that underscore issue...

Although I have to say the clear seperation I find underscore provides out-weighs the slight inconvenience of interupting qwerty standard finger placement or whatever it's called :P

Anyways, thanks for the input :)
User avatar
RobertGonzalez
Site Administrator
Posts: 14293
Joined: Tue Sep 09, 2003 6:04 pm
Location: Fremont, CA, USA

Post by RobertGonzalez »

I mix underscore/lowercase notation (procedural) with Hungarian notation (classes, objects, methods, properties). I very seldom mix the two. This gives me a little delineation when it comes to developing projects. It kinda goes without saying that I always use UPPERCASE for constants.
timvw
DevNet Master
Posts: 4897
Joined: Mon Jan 19, 2004 11:11 pm
Location: Leuven, Belgium

Post by timvw »

I tend to use camelcase for classes, methods and functions and underscores for variables.
Currently i'm considering to use camelcase but with the first letter in uppercase too, .net style.

I do not use hungarian, except for GUI elements.
User avatar
Buddha443556
Forum Regular
Posts: 873
Joined: Fri Mar 19, 2004 1:51 pm

Post by Buddha443556 »

feyd wrote:If working on a class that could have namespace issues -- often what class doesn't? -- I will prefix the classname to help separate it and give the classes a unified namespace. There's still potential for namespace collision, but it's less than without the prefix. :)
I do the same for all function/classes. The prefix helps me identify the origin of the code, the project/codebase from which it comes.
User avatar
Todd_Z
Forum Regular
Posts: 708
Joined: Thu Nov 25, 2004 9:53 pm
Location: U Michigan

Post by Todd_Z »

I wonder how difficult it would be to write a script to check the coding convention for consistency throughout a script.

It would be interesting to run a script on a set of files and see how many errors show up.

This could be an invaluable tool for n00bs to help them either develop their own style, or to help them stay away from errors
Roja
Tutorials Group
Posts: 2692
Joined: Sun Jan 04, 2004 10:30 pm

Post by Roja »

It needs some minor updates, but the coding guidelines for my old project are still the guidelines I generally follow:
http://www.kabal-invasion.com/guidelines.html
User avatar
Ambush Commander
DevNet Master
Posts: 3698
Joined: Mon Oct 25, 2004 9:29 pm
Location: New Jersey, US

Post by Ambush Commander »

Things I do

* $underscore_for_variables (clear seperation sells it to me)
* camelCaseForMethods()
* both_forFunctions() (but not at the same time)
* Classes_CapitalCamelCase_WithUnderscoreNamespacing
* descriptive names. If I abbreviate it, I make note in a comment
* uppercase for constants
* prefix for globals, usually $wg (a peculiarity I picked up from working with the MediaWiki codebase. Anything else looks weird)
* adhoc trailing _html, _sql, etc. to denote something okay for that context
* bracing style (can't believe no-one else brought this up):

Code: Select all

if ($condition) short_action(); //no braces
if ($condition) {
    // do stuff
}
function bang() {
    //do stuff
}
class ClassName
{
    // declarations
}
* four spaces per tab
* CR/LF (because I'm in Windows)
* adhoc extra spaces to make things look pretty
* single quotes for immutable strings, double quotes for strings that contain lots of 's or have interpolation
* lots of concatenation, never let the editor's line-wrap affect a string
* only // and /* */ for comments
* bit-masking needs constants
* ternary operators are fine
* code under E_ALL
* preg over ereg
* echo

Things I know about but don't use

* Hungarian notation - tried it, wasn't my style. Partially because I use an underscore to seperate variables
* Variable on right side of equality - I dunno. It just looks weird to me. And like Hockey, I've never run into a problem with the variables on the left
* PHPdoc - never could get around to doing that. good code should be self documenting
* File headers - they're a pain the arse trying to update them all

Interesting things that I don't do

* Prefixing arguments. Maybe I should do that...
* Only allowing single letter variables in loops

Things I used to do but don't anymore

* namespacing all classes in self-contained applications
* all caps for globals (now they're prefixed)

What's that?

* Linux style?
User avatar
Christopher
Site Administrator
Posts: 13596
Joined: Wed Aug 25, 2004 7:54 pm
Location: New York, NY, US

Re: Coding conventions

Post by Christopher »

Hockey wrote:So I decided that I am going to sit down and write a formal document explaining how and why I use certain conventions when writing PHP code.
Oh no ... we can't stop him can we. ;)

I think the issue of formatting variables, constants, functions, class names, etc. in PHP is generally settled. Like it or not, most everyone is using something close to the style guidelines defined by PEAR. The new Zend Framework was probably the last chance for a change of course and they ended up just conforming. So at this point anyone varying much from PEAR style in PHP is doing so either out of ignorance or to make some sort of personal statement. That means either you have better things to do, are clueless, or an iconclast.
(#10850)
User avatar
Ambush Commander
DevNet Master
Posts: 3698
Joined: Mon Oct 25, 2004 9:29 pm
Location: New Jersey, US

Post by Ambush Commander »

Well, there's some wiggle room. Like bracing.
User avatar
Christopher
Site Administrator
Posts: 13596
Joined: Wed Aug 25, 2004 7:54 pm
Location: New York, NY, US

Post by Christopher »

Ambush Commander wrote:Well, there's some wiggle room. Like bracing.
Yes. I see code with both this

Code: Select all

if ($condition) {
    // do stuff
}
And this

Code: Select all

if ($condition)
{
    // do stuff
}
and I never hear anyone say anything one way or the other. Most of the common styles have some trivial variations that really aren't worth noting.
(#10850)
Roja
Tutorials Group
Posts: 2692
Joined: Sun Jan 04, 2004 10:30 pm

Post by Roja »

arborint wrote:I think the issue of formatting variables, constants, functions, class names, etc. in PHP is generally settled.
It really isn't, as you will probably see from the phpbb formatting guidelines, the adodb formatting guidelines (are there any? heh), and mine.

Its deeply not a settled issue, and won't ever be. There are simply too many things to disagree about, and far too many good reasons on each side of each issue for any of them to be discarded out of hand.
arborint wrote:So at this point anyone varying much from PEAR style in PHP is doing so either out of ignorance or to make some sort of personal statement. That means either you have better things to do, are clueless, or an iconclast.
Personally, I think your statement regarding people preferring different defaults to be more along those lines - clueless about a *decades* long difference in programming languages when it comes to braces, variable naming, and more. Its not settled, it won't be, and name calling doesn't help. :)

Not to mention, the vast majority of PEAR cannot be used in GPL projects - making it hardly a "defacto" force for determining SQUAT. Its a large collection of packages, big deal. I touched a grand total of two PEAR packages in five years, and it did nothing to affect my coding preferences.
arborint wrote:and I never hear anyone say anything one way or the other. Most of the common styles have some trivial variations that really aren't worth noting.
Ah, but they are. Tabs v. spaces is incredibly worth noting. So is saving in unix (not windows) format. So is variable naming.

Just because you think the argument is settled, and doesn't matter doesn't change the reality that there are a huge variety of coding guidelines out there. Whether you have heard from projects that they prefer a coding style or not, it does matter, it is worth noting, and thats why numerous groups have documented their preferences.
alex.barylski
DevNet Evangelist
Posts: 6267
Joined: Tue Dec 21, 2004 5:00 pm
Location: Winnipeg

Post by alex.barylski »

Ambush Commander wrote:Things I do

* $underscore_for_variables (clear seperation sells it to me)
* camelCaseForMethods()
* both_forFunctions() (but not at the same time)
* Classes_CapitalCamelCase_WithUnderscoreNamespacing
* descriptive names. If I abbreviate it, I make note in a comment
* uppercase for constants
* prefix for globals, usually $wg (a peculiarity I picked up from working with the MediaWiki codebase. Anything else looks weird)
* adhoc trailing _html, _sql, etc. to denote something okay for that context
* bracing style (can't believe no-one else brought this up):

Code: Select all

if ($condition) short_action(); //no braces
if ($condition) {
    // do stuff
}
function bang() {
    //do stuff
}
class ClassName
{
    // declarations
}
* four spaces per tab
* CR/LF (because I'm in Windows)
* adhoc extra spaces to make things look pretty
* single quotes for immutable strings, double quotes for strings that contain lots of 's or have interpolation
* lots of concatenation, never let the editor's line-wrap affect a string
* only // and /* */ for comments
* bit-masking needs constants
* ternary operators are fine
* code under E_ALL
* preg over ereg
* echo

Things I know about but don't use

* Hungarian notation - tried it, wasn't my style. Partially because I use an underscore to seperate variables
* Variable on right side of equality - I dunno. It just looks weird to me. And like Hockey, I've never run into a problem with the variables on the left
* PHPdoc - never could get around to doing that. good code should be self documenting
* File headers - they're a pain the arse trying to update them all

Interesting things that I don't do

* Prefixing arguments. Maybe I should do that...
* Only allowing single letter variables in loops

Things I used to do but don't anymore

* namespacing all classes in self-contained applications
* all caps for globals (now they're prefixed)

What's that?

* Linux style?
Sounds like your style is very similiar to mine...you must be a top notch developer? ;)

Honestly, I've extracted a few good ideas from everything that has been said so far...

For instance...I always use single character identifiers for loop indices, but I always start with i

For now on...I think I'm gonna start with a and each time a new one is needed I increment the ordinal value and go from there.

I have run into bugs when dealing with deeply nested for loops, etc...and re-using a counter variable...so this new convention would eliminate that all together...

Pure genius I thought :P

Cheers :)
alex.barylski
DevNet Evangelist
Posts: 6267
Joined: Tue Dec 21, 2004 5:00 pm
Location: Winnipeg

Post by alex.barylski »

arborint wrote:
Ambush Commander wrote:Well, there's some wiggle room. Like bracing.
Yes. I see code with both this

Code: Select all

if ($condition) {
    // do stuff
}
And this

Code: Select all

if ($condition)
{
    // do stuff
}
and I never hear anyone say anything one way or the other. Most of the common styles have some trivial variations that really aren't worth noting.
I use the first and ignore braces all together if I can...

Perhaps ignoring braces is bad practice, but again, I've never personally experienced a bug due to missing braces on a single statement for loop, etc...

For the same reason some people don't like comments, I don't like using unnessecary lines, in this case the latter example...
Post Reply