Because we (being myself and my partner) are occasionally masochistic, we decided right after doing a huge change to our current project update, one we likened to throwing a nuke in out app, we also decided we needed to come to terms on variable naming schemas, specifically regarding variables.
Our “schema” so to speak, was a holdover from our ColdFusion days, which included using camelCase with a letter prefix indicating type (so a for array, s for structure in CF and string in PHP, o for object). As we moved into PHP and using Zend Framework, we sort of half adopted their conventions of using underscores to separate words instead of camel casing, but we weren’t consistent.
As a result, we might have a funky mix of both in a single line, like this:
$qPositions = $ dbc->query($sGetPositions);
Or even in a function declaration, like this:
public function saveDirectoryProfile($personID, DirectoryProfileEntity $bDirectoryProfile, $specializations = NULL, $requestor_id) { }<span></span>
So to come to some agreement on what we wanted to do going forward, we decided to Google PHP naming conventions to see what other groups do or if there is some sort of recommendation out there (since PHP really has nothing formal other than the language itself).
Instead, we landed into the wonderful world of PSR, which we had heard about but never really looked at in-depth or considered using. Since it came up in the search results, we read over PSR-1 and PSR-2, which speak to coding conventions and formatting preferences.
And, in our standardization mania and deciding we needed to have a little “grow up” again moment in our coding lives, we decided to implement both, right now, in our current project.
I admit, while I agreed to it, I’m also chafing at it badly. Many of their MUSTs are ugly to me aesthetically when looking at my code and make no sense. So I’m gonna vent a little about the things I’m struggling with:
- I abhor the 4 spaces crap for indenting instead of tab (and no, I don’t care if you disagree and yes I did read and do understand the logical argument for it, I still hate it :-P).
- I really hate using the curly braces method for controls. I much prefer the alternative syntax and it’s what I use in all my code. (i.e. doing if(): with endif; instead of if() {}. I find the alternative clearer and easier to read myself. The PSRs don’t specifically address this, but since it says must use braces, we are talking the presumption that alternative syntax is disallowed (and if this is wrong, please for the love of my programmer’s sanity tell me so because I HATE CURLY BRACES!!!!)
- Leaving off the ?> just feels wrong to me and incomplete, as if you just walked out the house and left the door closed.
- The soft/hard line limit (the meaning of which is still leaving my scratching my head), it seems so arbitrary and pointless. Do that many people really still code in miniscule screens?
- Having opening curly braces for classes and methods also bugs me. It just looks ugly, and I see no reason to be inconsistent with the control structure formatting
- Did I mention hating spaces and curly braces for control structures? 😛
Notice, of course, the irony that PSR does not, in fact, discuss variable naming at all. It does prescribe conventions for class names (StudlyCaps), class constants (all upper case with underscore separators), and method names (camelCase), but not the variables we were looking for guidance on. LOL
So paradigm shift in how I code, we’ll be spending quite a bit of time bringing things to standards, and we still didn’t get an answer on the original question. Dreamweaver CS6 is my IDE of choice (and before anyone comments on why X is better, NO – this post still holds true and I’m not switching), so I also need to do what I can there to have it coax me into following the standards. Though I think mostly it is just the indenting thing.
Weee!!!
Oh, and for the curious, with regards to the variables, we did finally decide:
- Regular variable names and properties MUST NOT be prefixed with a letter to indicate variable type (i.e. aVariable for array, oVariable for object, etc)
- Variable names MUST be all lower case with underscores between words and named to clearly identity contents
- Arguments MUST be all lower case with underscores between words and named in a way that clearly identifies its usage/affects in the function
We also augmented the PSRs with our own standards, some of which restrict choices left in the PSR and some to fill in missing spaces:
- Files MUST use only <?php tags
- Methods SHOULD BE ordered with public methods first, then protected ones and finally private ones; methods within each section MUST be in alphabetical order
- Class properties MUST be declared before methods
- Properties MUST NOT have blank lines between them, other than to separate groups of properties of differing visibility (i.e. public, protected, private)
- Code within the <?php tags SHOULD BE be indented, as a whole one level in, however flush left is also considered acceptable
- Method invocations (i.e. $example->function()) MUST BE on one line when fewer than 3 invocations. After 3, invocations MUST BE put on a separate line, indented once. The following are pre-agreed exemptions to these requirements:
- invocations requiring multiple, lengthy, or array type arguments that lead to less readable code (for example, ViewModel configurations with template setting)
- Zend DB setups (i.e. Select/Insert/Update/Delete) and form configurations ($this->function() and creating form elements and filters) can be put one per line regardless of whether it has 3 invocations or not
We’ll see how this goes…I’m sure we’ll be discussing further changes, tweaks, etc. over the coming days as we go through our code and clean things up. At least with the variable naming itself, we can mostly clean those up quickly…the PSR stuff is trickier.
My partner uses ZendStudio 13.5 which has a function to auto implement PSR-2, but when he ran it, it broke our entire app because of how it moved stuff around, so we had to revert that (thank you SVN for the 10000th time LOL).
So for now, we’re doing it bit by bit, file by file as we work on the code for the actual work we’re supposed to be doing, then we can use something like PHP_CodeSniffer to find issues for hand cleaning once we’re done our more selective clean ups with search/replace and reg exs.
(and for the record, no, I will not be implementing any of this on personal projects, and will stick to my own standards there J)