Coding Standards as an XML spec - Discussing the Avenues of Cooperation between Codesniffer, Beautifier, PhpDocumentor, and others in the PEAR family

Hi, A discussion arose between a number of us; primarily myself , Chuck Burgess, Christian Weiske and Greg Sherwood about the possibilities of representing Coding Standards in such a way that any tool that should be aware of them and/or generateѕ code can do so without running the risk of reversing the work done by a developer who wrote according to the chosen Coding Standard. In other words, for example, after investing a lot of time in getting the code for the Date_Holidays package up to Standard I would be seriously put out if I were to run docblockgen or any other tool on that code and found it actually reversed/undid a lot of the changes I made and that it dramatically increased the count of detected errors and warnings detected by the PHP_CodeSniffer's phpcs tool. I'm sure most of us can relate to this scenario ;-) Please read the following to get an idea of what we are about. Ken ----- Forwarded message from Ken Guest <ken@linux.ie> ----- Subject: Coding Standards as an XML spec - Discussing the Avenues of Cooperation between Codesniffer, Beautifier, PhpDocumentor, and others in the PEAR family From: Ken Guest <ken@linux.ie> Date: Mon, 30 Jul 2007 14:19:54 +0100 To: Claudio Bustos <clbustos@surnet.cl>, Greg Sherwood <gsherwood@squiz.net>, Marc McIntyre <mmcintyre@squiz.net>, Greg Beaver <greg@chiaraquartet.net>, Joshua Eichorn <jeichorn@JoshuaEichorn.com>, Chuck Burgess <demon.gene@gmail.com>, Andrew Morton <drewish@katherinehouse.com>, Michel Corne <mcorne@yahoo.com> Cc: Christian Weiske <cweiske@cweiske.de> Reply-To: ken@linux.ie Hello, Myself, Christian Weiske, and Chuck Burgess were considering how php_beautifier alters code that php_codesniffer shows to be correct. Similarly we wouldn't want docblockgen to have a negative impact on the quality of the code it has been run on. We came to the conclusion that it makes sense for each 'codesmith' tool that either alters or reviews source code, need to "sing off the same hymn sheet"; especially when it comes to Coding Standards. The only way to do this that seems feasible to us is to have a format to parameterize a set of commonly shared rules - a "standards specification" of sorts. This spec would drive the different tools' decision making processes and if all the tools implement the rules correclty, there should not be any problems caused by any overlap between the tools or the order in which they are run. We're thinking that this Code Layout Definition, or Code Layout Specification, if you will, would have default values defined that tools should follow if they are not defined explicitly in the definition of the specific set of Coding Standards - much the same way that there are defaults set out in the HTML DTDs that are over-ridden in HTML documents (alignment, border width etc). One major advantage of this push towards establishing a common format to specify these Coding Standards is that our tools can be used to support other Coding Standards [an example being the Mantis Coding Standards] and so help grow/evolve things from there. We would be very interested in knowing what you think of this... -- Ken Guest Mobile: +353 86 8252 141 http://blogs.linux.ie/kenguest/ ----- End forwarded message ----- Greg replied: From: Greg Sherwood <gsherwood@squiz.net> Date: Tue, 31 Jul 2007 10:22:54 +1000 To: ken@linux.ie Cc: Claudio Bustos <clbustos@surnet.cl>, Marc McIntyre <mmcintyre@squiz.net>, Greg Beaver <greg@chiaraquartet.net>, Joshua Eichorn <jeichorn@JoshuaEichorn.com>, Chuck Burgess <demon.gene@gmail.com>, Andrew Morton <drewish@katherinehouse.com>, Michel Corne <mcorne@yahoo.com>, Christian Weiske <cweiske@cweiske.de> Hi Ken, I think that while this is a great idea, I don't see how it could be implemented. I did try to do this when I first started PHP_CodeSniffer, but it got too hard too fast. A standard for defining coding standards would be terrific, especially something easy to read and write like XML. The problem I have is that I don't believe that a text-based standard could ever define all the rules that a coding standard enforces. By locking down coding standards into a text-based file, you are basically saying that there are a certain number of rules that can be enforced (e.g., line length, indentation, function declarations etc.). I think that is dangerous because it means that the standard needs to be changed for every modification to the tool. For example, I just added a new sniff to PHP_CodeSniffer to check the nesting level inside functions to ensure it doesn't get too high. For me to be able to add that to a coding standard defined in XML, I'd have to get a change to the standard approved and then have PHP_CodeSniffer and other tools modified to accept the new standard. That would take far too much time. Plus, that particular standard doesn't really mean anything to PHP_Beautifier, so there is no reason to implement it besides ensuring it conforms to the standard. So while I think this idea is great, I think there are some issues that need to be worked through, and those issues are not trivial. I don't have any ideas to solve those issues at the moment, but it anyone else does, I'd be very interested in trying to work towards a common standard. Greg ------------------ He then sent this missive: From: Greg Sherwood <gsherwood@squiz.net> Date: Tue, 31 Jul 2007 10:25:48 +1000 To: ken@linux.ie Cc: Claudio Bustos <clbustos@surnet.cl>, Marc McIntyre <mmcintyre@squiz.net>, Greg Beaver <greg@chiaraquartet.net>, Joshua Eichorn <jeichorn@JoshuaEichorn.com>, Chuck Burgess <demon.gene@gmail.com>, Andrew Morton <drewish@katherinehouse.com>, Michel Corne <mcorne@yahoo.com>, Christian Weiske <cweiske@cweiske.de> Sorry, I forgot the other thing I was going to mention. I have some coding standards that are specific to particular products or development teams. They check things in the code that are very specific to the product or team, like the method of executing a DB query's error checking, or the specific way messages are translated (or not). We would also need to consider how our tools could implement these type of specific (and very useful) standards using a common format. Greg ---------- Christian Weiske added: From: Christian Weiske <cweiske@cweiske.de> Date: Tue, 31 Jul 2007 09:23:33 +0200 To: Greg Sherwood <gsherwood@squiz.net> Cc: ken@linux.ie, Claudio Bustos <clbustos@surnet.cl>, Marc McIntyre <mmcintyre@squiz.net>, Greg Beaver <greg@chiaraquartet.net>, Joshua Eichorn <jeichorn@JoshuaEichorn.com>, Chuck Burgess <demon.gene@gmail.com>, Andrew Morton <drewish@katherinehouse.com>, Michel Corne <mcorne@yahoo.com> Greg, > A standard for defining coding standards would be terrific, > especially something easy to read and write like XML. The problem I > have is that I don't believe that a text-based standard could ever > define all the rules that a coding standard enforces. By locking down This is why I think that we should define a set of rules and share only the parameters between applications. E.g. we define that we have rules like - max line length - space between "if" and "(" and all those rules have parameters - like the number of chars in max line length, and the number of spaces between if and "(". This parameters could be shared among apps, but the rules (and their internal names) need to be defined before. All the programs would need to implement them, of course, before they can use the parameters. But this wouldn't be that bad since the programs can tell the user "I don't support this rule". ------------- I replied: From ken@linux.ie Tue Jul 31 09:37:11 2007 Date: Tue, 31 Jul 2007 09:37:11 +0100 From: Ken Guest <ken@linux.ie> To: Christian Weiske <cweiske@cweiske.de> Cc: Greg Sherwood <gsherwood@squiz.net>, ken@linux.ie, Claudio Bustos <clbustos@surnet.cl>, Marc McIntyre <mmcintyre@squiz.net>, Greg Beaver <greg@chiaraquartet.net>, Joshua Eichorn <jeichorn@JoshuaEichorn.com>, Chuck Burgess <demon.gene@gmail.com>, Andrew Morton <drewish@katherinehouse.com>, Michel Corne <mcorne@yahoo.com> This is more or less what I am thinking - we need to define the specs for the basic 'building blocks' of Coding Standards first; indentation, parenthesis placement, spacing around the '=' character, which comment markers are valid etc. The programs can either, much as with Internet Explorer's blink tag for want of a better analogy, implement/support it or simply ignore it. The preference would be of course that nothing is ignored; but we have to be realistic too. Rome wasn't built in a day, nor were the W3C HTML specs [considering completed the draft for version 5 last month]; it wouldn't be realistic to expect us to suddenly produce a perfect XML spec/representation for Coding Standards at the very first attempt, but at the least we can make a start at it and then refine/fix/enhance what we have done. k. -- Ken Guest Mobile: +353 86 8252 141 http://blogs.linux.ie/kenguest/