Coding Standards
I've recently come across http://pear.php.net/manual/en/standards.php, which got a few ideas jumping about my head, and reminded me of a tool I use from time to time for curiosity purposes more than anything - phpcs or PHP CodeSniffer (http://pear.php.net/package/PHP_CodeSniffer/).
I occasionally run phpcs against some of the codebases I work on, just to see if there seems to be any structure or standard being followed throughout the system. The results are usually verbose and stressful to even begin trying to fix, and sometimes wonder if coding standards are used effectively anywhere.
With the many techniques and ways of completing a task in PHP and with PHP developers becoming more and more OOP oriented, developers are beginning to play around with inheritance and abstraction, namespaces and interfaces, getters and setters - All the buzzwords and terms which lead to more and more overly complex code for no reason other than - "we used all of the above", and as a result "our code must be cutting edge".
But the issue here comes at the cost of maintenance. I guess this can be classed as Technical Debt and it isn't necessarily the fault of the developer either.
In some cases developers may walk into a team where no standards are currently in place, and it is up to that developer to set a standard. Some developers will be happy to struggle along and hack and slash code until it works and leave satisfied at that, but there will come a point when they suddenly realise a standard is the way forward. But what should a general coding standard cover?
I definitely don't think a coding standard document should be hundreds of pages long, however I definitely don't think it should be a couple of sentences. Somewhere in the middle I guess is between 8 and 10 pages. Just long enough to set the foundations for new developers, and not to long to lose them that they wonder what they're walking into.
I think a common coding standard should cover 6 key issues:
1. Naming Conventions
2. File Naming and Organization
3. Formatting and Indentation
4. Comments and Documentation
5. Classes, Functions and Interfaces
6. Testing
Each of these, I'll discuss in a few lines.
1. Naming Conventions
Naming conventions here should cover pretty general variable naming standards. Although some of the standard may be obvious to programmers of say C or Java, as they would be used to explicitly declaring the scope of their variables, it might be good practise to adopt a similar standard even within PHP where things are a little more flexible. For example, would you like string variables to be prefixed with str (strName), or integer values to be prefixed by int(intAge). Should variables be all lowercase with underscores(str_name) to separate "words", or camelcase (strFirstName) to represent new words?
2. File naming and organisation
File naming and organising should specify how files are named, and the folder structure they should follow. For example, are all your class files in a folder called classes, or a sub folder structure application/core/classes. Or are your files grouped into modules, and within these modules, a classes folder exists. Where do images go? Both structural and customer uploaded content if applicable? Would you rather everything was above the public_html directory, and accessed through a controller file? specify this site and file organisation at this point.
3. Formatting and Indentation
Some developers swear by tabs, some swear by 4 spaces. Some just want to cram as much as possible on one line! Decide on a standard that you would like everyone to follow that is easy to read and maintain. If developers are using different IDE's, tabs might not be a good idea, as some IDE's have different indents for tabs, whereas 4 (or 6 or 8 whatever you like), spaces are pretty easy to replicate no matter what IDE is used.
4. Comments and Documentation
I remember this from as far back as High School - "Documentation, documentation, documentation". The envy of my computing life, but now I'm in the real world, how wrong I was to hate it. If I could have documentation for every piece of code I've used it would be amazing. Bottom line here, developers don't like documenting, but if you set this in your standard, to at least document the purpose of classes or files in the header (I'm thinking in phpDoc style here), and comment complex pieces of code, using a certain comment style, this will go down well if developers can see this across other code they'll be more inclined to follow suit.
5. Classes, Functions and Interfaces
A standard here, could be that concrete classes are never passed into an objects, and every class must implement an interface. How your classes are named and how methods are named should also fall under this category, for example, class names should always be capitalised and singular (eg Cart or Post), and all methods should be private except getters and setter which are prefixed with 'get' or 'set', and camelcased (eg getPostTitle(); or setDeliveryCharge();)
6. Testing
How is your code tested? Do you have a test suite that is run on check in, or do you manually write tests for your methods as and when you create the methods, showing inputs and outputs. A lot of organisations these days are moving towards CI (Continuous Integration) solutions where test suites are automatically ran (a blog-post I'm looking forward to writing). Some have unit or functional tests which are manually ran before code is checked into a repository, or some just look at the code and go 'ok, yeah that works'. The latter of which many of us have been pretty good at in the past. You may also have a QA team, person or phase of development to go through and sign off checklists before work is passed back to the client, whatever method works for you, document it and make sure everyone does the same.
Crikey, I haven't half went on there! Thank you if you're still with me. The bottom line I guess is, are coding standards a good thing or a waste of time and money? I believe they are a good thing. If implemented correctly, they should set the foundations for any new developers joining your team, and maintaining the highest standards of code quality. It also leads on to maintenance, that if a piece of work is being picked up by another team, they're not completely in the dark, they know if a variable is all in capitals its a constant defined in the configuration file, and this configuration file is always in the same place on every project. Also, if they're working on a specific area, they know to checkout unit tests or certain areas of documentation for details on that area of code.
Thanks for reading.
I occasionally run phpcs against some of the codebases I work on, just to see if there seems to be any structure or standard being followed throughout the system. The results are usually verbose and stressful to even begin trying to fix, and sometimes wonder if coding standards are used effectively anywhere.
With the many techniques and ways of completing a task in PHP and with PHP developers becoming more and more OOP oriented, developers are beginning to play around with inheritance and abstraction, namespaces and interfaces, getters and setters - All the buzzwords and terms which lead to more and more overly complex code for no reason other than - "we used all of the above", and as a result "our code must be cutting edge".
But the issue here comes at the cost of maintenance. I guess this can be classed as Technical Debt and it isn't necessarily the fault of the developer either.
In some cases developers may walk into a team where no standards are currently in place, and it is up to that developer to set a standard. Some developers will be happy to struggle along and hack and slash code until it works and leave satisfied at that, but there will come a point when they suddenly realise a standard is the way forward. But what should a general coding standard cover?
I definitely don't think a coding standard document should be hundreds of pages long, however I definitely don't think it should be a couple of sentences. Somewhere in the middle I guess is between 8 and 10 pages. Just long enough to set the foundations for new developers, and not to long to lose them that they wonder what they're walking into.
I think a common coding standard should cover 6 key issues:
1. Naming Conventions
2. File Naming and Organization
3. Formatting and Indentation
4. Comments and Documentation
5. Classes, Functions and Interfaces
6. Testing
Each of these, I'll discuss in a few lines.
1. Naming Conventions
Naming conventions here should cover pretty general variable naming standards. Although some of the standard may be obvious to programmers of say C or Java, as they would be used to explicitly declaring the scope of their variables, it might be good practise to adopt a similar standard even within PHP where things are a little more flexible. For example, would you like string variables to be prefixed with str (strName), or integer values to be prefixed by int(intAge). Should variables be all lowercase with underscores(str_name) to separate "words", or camelcase (strFirstName) to represent new words?
2. File naming and organisation
File naming and organising should specify how files are named, and the folder structure they should follow. For example, are all your class files in a folder called classes, or a sub folder structure application/core/classes. Or are your files grouped into modules, and within these modules, a classes folder exists. Where do images go? Both structural and customer uploaded content if applicable? Would you rather everything was above the public_html directory, and accessed through a controller file? specify this site and file organisation at this point.
3. Formatting and Indentation
Some developers swear by tabs, some swear by 4 spaces. Some just want to cram as much as possible on one line! Decide on a standard that you would like everyone to follow that is easy to read and maintain. If developers are using different IDE's, tabs might not be a good idea, as some IDE's have different indents for tabs, whereas 4 (or 6 or 8 whatever you like), spaces are pretty easy to replicate no matter what IDE is used.
4. Comments and Documentation
I remember this from as far back as High School - "Documentation, documentation, documentation". The envy of my computing life, but now I'm in the real world, how wrong I was to hate it. If I could have documentation for every piece of code I've used it would be amazing. Bottom line here, developers don't like documenting, but if you set this in your standard, to at least document the purpose of classes or files in the header (I'm thinking in phpDoc style here), and comment complex pieces of code, using a certain comment style, this will go down well if developers can see this across other code they'll be more inclined to follow suit.
5. Classes, Functions and Interfaces
A standard here, could be that concrete classes are never passed into an objects, and every class must implement an interface. How your classes are named and how methods are named should also fall under this category, for example, class names should always be capitalised and singular (eg Cart or Post), and all methods should be private except getters and setter which are prefixed with 'get' or 'set', and camelcased (eg getPostTitle(); or setDeliveryCharge();)
6. Testing
How is your code tested? Do you have a test suite that is run on check in, or do you manually write tests for your methods as and when you create the methods, showing inputs and outputs. A lot of organisations these days are moving towards CI (Continuous Integration) solutions where test suites are automatically ran (a blog-post I'm looking forward to writing). Some have unit or functional tests which are manually ran before code is checked into a repository, or some just look at the code and go 'ok, yeah that works'. The latter of which many of us have been pretty good at in the past. You may also have a QA team, person or phase of development to go through and sign off checklists before work is passed back to the client, whatever method works for you, document it and make sure everyone does the same.
Crikey, I haven't half went on there! Thank you if you're still with me. The bottom line I guess is, are coding standards a good thing or a waste of time and money? I believe they are a good thing. If implemented correctly, they should set the foundations for any new developers joining your team, and maintaining the highest standards of code quality. It also leads on to maintenance, that if a piece of work is being picked up by another team, they're not completely in the dark, they know if a variable is all in capitals its a constant defined in the configuration file, and this configuration file is always in the same place on every project. Also, if they're working on a specific area, they know to checkout unit tests or certain areas of documentation for details on that area of code.
Thanks for reading.
Totally agree! The times I've had issues with a piece of code have pretty much all been down to lack of coding practices followed. What I find worst though, are lack of common naming conventions for functions, variables and files.
ReplyDeleteEven worse is when those variables aren't at all descriptive of what it's doing. If you call your variable $data and it's in a global piece of code, I'm going to get my rage on.