Having worked within a variety of different programming languages, I realize that there are obvious syntactic differences from one language to the next. By the variance is not just with syntax. Standards for variable and function declaration differ quite a bit as well. Even within a single language, opinions vary as to which standards are considered best practice. Since I have every intention of releasing my code to the open source community, I’d like to develop a standard coding format that conforms as much to the normal standards as possible.
My second official release is a PHP-MySQL scaffolding utility known as MBG Scaffolder. The downloadable version of this software consists of a single file where all comments and excess white space have been removed. This assists end-users because the download size is smaller and the utility takes less time to load when in use. The obvious disadvantage to this format is that it’s not entirely user-friendly and certainly doesn’t lend itself to future development by outside programmers. So the next step in this process is to release a non-minified version of the code with white space and full comments intact.
The current MBG Scaffolder package does include end-user help documentation. These docs are designed to assist users with learning the ins and outs of the web interface only. End users are typically not concerned with how back-end code works, only that it does so without errors. But the current release of this package is decidedly lacking in useable developer documentation. I hope to remedy this in future releases to make it easier for other developers to utilize this package and even recommend changes to help grow and improve the code base.
With that in mind, I’m interested to know if there’s a single resource available (hard copy or online), that outlines universal coding standards for PHP developers. I’m putting this out to the rest of the development community in hopes of getting some useful feedback. My specific focus at the moment is on comments within my code since I’m trying to assist developers as much as possible. From my brief research, it seems that many developers follow the JavaDocs example for commenting. But is the norm for the majority of developers? If not, what are some other recommended styles for commenting within PHP?
In my brief research I came across several good resources that may assist other PHP developers out there. On the PHP.net site, under the Pear Manual, there is a great document that outlines sample comments that they recommend for all PHP code. As I noted previously, these standards are based on JavaDocs standards with only a few exceptions. I discovered another well-versed set of standards written by Fredrik Kristiansen of DB MediaLab in Norway. His version appears to be a PHP-based translation of standards based on Todd Hoff’s C++ coding standards. Another possible resource for developers is the standards written for working within the Zend PHP framework. However, these docs appear to be somewhat Zend-specific and are a bit more stringent in what is and is not considered acceptable. But as a loose guide it might prove useful.
Sticking with the first resource under the Pear manual, PHP offers a piece of software that will automatically parse your source code and effectively output a working manual based on the comments within the code. The format for comments must comply with pre-established standards though so this won’t work with just any code. The software is known as phpDocumentor and is available for free to any developers who wish to use it. There are probably other good resources for coding practices to be found. These are just a few of the ones I discovered that seemed to conform to the standards I’ve seen in the past. Feel free to leave feedback on other good resources if you know of any others.