MODX Coding Standards

1

I’ve been looking at this page in the MODX 3 docs, and noticed that in a number of cases, it doesn’t reflect the style of the MODX 3 core code.

I don’t know if this is because some code hasn’t been converted, the page is outdated, or the coding standards are somewhat loose.

The guidelines on that page are also a little vague.

For example, " Beginning brackets do NOT linebreak. They start one space after the end parenthesis, as according to traditional Unix policy."

It’s not clear what constitutes a “beginning bracket.” From the text and examples, it seems that this would include curly braces (and, imo, it’s incorrect to call them brackets, though some people do use that term for them, as does Wikipedia).

In the MODX 2 core code, curly braces for classes and functions/methods are generally on the same line (as they are in my code).

In MODX 3 braces for classes are generally on a new line, but those for functions/methods are not. The PSR-2 examples show curly braces for some functions on a new line, but I couldn’t find any “rule” for this, and those for functions with the arguments on separate lines, put them after the final ) .

Another issue, not mentioned in the docs is the many instances of else if rather than elseif in the core code. PSR-2 (should PSR-2 be mentioned on the page? It’s not) says it should be elseif which could be fixed with search-and-replace.

The examples on the page also show no spaces between arguments/parameters. This practice is inconsistent in both MODX 2 and MODX 3, though no spaces seems to be more prevalent. FWIW, I prefer spaces. For one thing, it allows lines to break there on smaller screens when example code is inline in a paragraph rather then in <pre> tags. I also think it makes the code easier to read.

Here’s another rule: " * Always name PHP class files in name.class.php format."

This is no longer followed in MODX 3.

It’s not a coding style issue, but while I’m at it, it’s MODX 3 (not MODX3), right? Or is it required to be MODX Revolution 3 in all cases?

In my code, I generally put curly braces on the same line for both classes and functions/methods (which is how they are generally in MODX 2), and I put spaces between arguments.

My biggest concern here is what style should be used in example code in, say, a new edition of MODX: The Official Guide and my MODX extras? Can I continue to put all curly braces on the same line and spaces between arguments?

2

Sorry, PSR-2 is deprecated, I meant PSR-12, though I don’t think that changes any points above, except that PSR-12 examples show spaces between arguments.

3

I never use “elseif”! I think I did in the distant past, but no more. “else if” reads better and makes it easier to insert lines of code into IF statements and move them around.

4

I think maybe that’s just poorly worded. It sounds like this doesn’t refer to bracket (or a brace) that begins a line, but begins something else, like the content of a function or IF statement, etc,:

function something() {

if (some test) {

instead of what some people do:

function ()
{

if (some test)
{

5

What’s the procedure in MODX 3?

6

The 3.x code has not been updated in one fell swoop, but we do have a codestyle formatter rule based on PSR12 that’s being run against every PR, so gradually things will become more consistent.

The code standard doc has not been updated from the 2.x version at this time, so what you’re seeing there is probably a decade or so old.

The PSR-12 document itself is a good reference of what’s a PHP-wide “best practice” for the expected code styles in PHP. There will be minor deviations due to BC , but that’s what we’re aiming for.

In your book I’d focus on legibility rather than strictly meeting any standard. If the same line looks better because it’s more condensed, go with it. It’s just a stylistic choice in the end.

7

Thanks!

That page should probably have a MODX 3/PSR-12 section added.

The stuff I’m writing may be read in eReaders with large print, so I’ve had to ignore some common standards. Some nested code sections have 2-space indents, otherwise, the code would be almost impossible to read (AFAIK, most eReaders don’t have horizontal scroll).

PSR-12 says “Closing braces MUST be on their own line and MUST NOT be preceded by a blank line.”

That’s not what I’ve ever done, and frankly, I’d prefer not to have dozens of extra pages, and unnecessary page breaks in the middle of code just to move the opening curly brace on all classes and functions to the next line. :wink: I’ll definitely explain the MODX 3/PSR-12 coding style to readers and tell them why I haven’t followed it.

I’m just wondering how much keeping the braces in the same line would upset MODX core coders. :wink:

8

Being brutally honest, as a potential reader of the updated version I’d skip this chapter without a second thought.

There’s certainly value in explaining how the core is built and why xPDO models are in a certain place and services in another (or what even is the difference between a model and a service), but coding style is a very boring detail of that very big picture. The book is already massive (if it’s any like the first edition, that is), I would suggest not spending more time/trees on explaining an industry standard coding style or why you’ve chosen to diverge.

Someone buying the book wants to learn about MODX, not about the position of a bracket (… or if it should be called a curly brace).

None at all. It’s only been adopted to follow the industry and try to bring some more consistency to a decade-old codebase.

9

I imagine you’d be skipping a lot of the chapters. :wink:

FYI, it’s not a chapter, it’s a few paragraphs in the Appendix, and that whole Appendix section will probably be removed. The book should be shorter once I remove all the references to Evolution, though it will have some new stuff added. Amazingly, in spite of its age, people are still buying the first edition.

That said, I appreciate your input. I wasn’t looking forward to reformatting all the code.

1 Like