Conventions and Standards for MODx Development

While doing a little debugging on a RichText widget problem, I began to wonder about what we’re doing in the way of creating a set of conventions and standards that all developers should follow while developing various things for MODx. The issue was raised when Ryan created a global CSS class name for the RichText widget when it appears on the frontend. My thoughts were that names for CSS classes that are assigned within the core code should be standardized so as to not cause confusion. As such, Ryan suggested I make a post about this and get the ball rolling. So, here’s some things to think about and some standards that I think we should follow close to the letter. These standards apply not only to the development of plugins, modules, snippets, and such but also to core code and files as well.

PHP Coding Standards

The PEAR site probably has the best methods for PHP coding standards (http://pear.php.net/manual/en/standards.php). Everything from using a 4 space indent (no tabs) to the use of curly braces in control structures is briefly covered. The content is brief but the ideas presented are such that it may take a little practice to get used to. In the end, if everyone follows them then the result is code that is easier to read and maintain...especially for those who are picking up the code for the first time. Whether you’re working on core code or a snippet, its a good idea to be very consistent with how you code. These guidelines will help immensely with this.

Comments

One of the things that is of the utmost importance is the use of comments. Comments, just like the rest of your code, should be well structured and follow the flow of your code. I usually like to break up my code in sections and use a comment just before a block of code to comment on what the overall block is used for. Not only does it make the code easier to read, but other people looking at the code will clearly understand why I did this or why I did that.

Speaking of comments, it would probably be a really good idea to implement some sort of standardized way of marking up a core file, snippet, plugin, or module with a starting comment. For instance, consider the following comment at the beginning of the FCKEditor plugin code:



Perhaps a better approach would be to use some standardized names for certain pieces of information. Now, with that in mind, consider the following alteration:



Does that make much more sense? Granted, it’s not set in stone, but the information we provide at the beginning of any core file or code (snippet, module, etc.) should probably be a little more standardized in the way we present it.

Naming Conventions

This is a little more tricky one. Exactly what should the name of a file, function, or class be? This is one area that should really be thought over a little bit. There’s probably a million ways we could address the naming conventions in functions, classes, and variables. But one good rule to keep is that unless a given function, class, or variable is private within the scope of your code, it’s best to keep the name very unique. A good suggestion is the start the name of the unique function or variable with the name of your application followed by an underscore then the name of your function or variable.

In the case of filenames, I honestly think that there should be no uppercase letters in the filename under no circumstances. Considering that Apache filenames are case-sensitive, it’s probably a good idea to keep all filenames as lower-case...not to mention that it’s so easy to forget that a given include file has an upper-case letter in it, thus giving you an error when you attempt to include it in your code.

CSS Class Names

Whether they are used within a snippet, module, or assigned within the core code as a global CSS class, it’s important to pay attention to the names being used for any given CSS class. For instance, Ryan recently assigned a class name to the DIV that wraps an instance of a RichText widget. At first, he used the name "MODX-rte". Granted, it works and it’s fairly unique...but I felt we could do better and standardized the method used for global CSS classes within the core. So, I suggested "MODx_RichTextWidget" as the class name. Not only does it tell the developer that it’s a "MODx" CSS class, but it also tells the developer what it’s used for making it much easier to deal with when the class is assigned to a stylesheet.

These are just a few of the standards and conventions I’m thinking about. There’s certainly more to think about here and I would love to hear everyones thoughts. If anything, perhaps we should consider drafting up some standards and conventions for MODx development. This will help out things quite a bit in the future as we continue to expand and grow.

Jeff

This sounds great. I brought this up a LONG time ago in "another" forum and got blasted for trying to make people code a certain way. Which totally missed the point. Beauty is not in chaos, it is in organization.

I’ve been assigning unique CSS class names to my snippets for ages. For instance, all my ListMenu classes begin LM_ which isn’t terribly specific, but was better than anything else I was seeing. I’m all for creating a standard of some sort. The visionaries here I’m sure recognize standards as a means to allow greater freedom, not restrict it.

Bravo. (or should I say "Bravado" )

Thanks Jeff and Jared,

I think this also could also get down to the nitty gritty of how "config" blocks are set up and maintained and sections of code. Jared’s done some great stuff here and his style has morphed over time I’ve noticed. It’s getting increasingly more compact and organized. Whitespace is a big thing for me too.

This could even get into best practices for doing a loop where you call a MySQL from the DB each time vs. doing one query outside the loop then looping through and doing array manipulations. Scalability and performance is important (or I should say will be now that the basic features are being nailed down and it’s time to focus on that).

Any other thoughts?

Quote from: rthrash at Oct 19, 2005, 03:40 PM

This could even get into best practices for doing a loop where you call a MySQL from the DB each time vs. doing one query outside the loop then looping through and doing array manipulations. Scalability and performance is important (or I should say will be now that the basic features are being nailed down and it’s time to focus on that).

This was one feature of ezsql that I really liked; you could use a query with "null" and it would actually be using a cache of the query instead of going all the way to the database again. In one snippet, I needed the same information from the database in three different loops, one or more of the IF conditions could be true. So I made the query outside the IF condition and the loops, then used "mysql_data_seek($results, 0) in the second and third loop to start again using the same query results, just checking for different values in the results, instead of having three queries, any one or more of which could be repeated in the loop. I feel that 20 and more queries in generating a single page of HTML is kind of excessive. There should be some way of reducing that.

Look like you get everything cover! I just want to add a couple things:

Naming conventions

* Classes: should start with an uppercase char
* Functions: should start with a lowercase char
* private functions: should start with an underscore (as an extra you can also add the phpdoc @access private)
* Constants should always be all-uppercase

Comments

Please use phpDoc-style comments, so that phpxref can be use to do the documentation from the code.
An example:

<?php
/**
* my foobar class.
* @author TeRanEX
*/
class FooBar extends Bar {
function doSomething() {
echo ’Hello world’;
}
}
?>

More info on this can be found at the phpDoc Manual

One more thing with the propose comment in the header bloack to keep track of who make modification is good except that it can take up a lot of line if many people making change to the code. Is there an alternative format:

For example:

Name Date Reason/Comment
Raymon 2005-10-10 Initial
Jeff 2005-11010 Bug fixes etc.

What do you think?

Thanks