Modules, plugins & snippet optimisation ?

FYI, I split the topic to a new one to focus on Multi-language best practices as that’s a bit of a more specific topic which I want to get into a new release ASAP.

Please continue to discuss general code optimization here.

Great, thanks Ryan.
It just seems to me that no one is that interested in talking about code optimization and best practices right now. lol

Hopefully me and Guillaume can come up with something.

Quote from: Djamoer at Mar 14, 2006, 02:25 PM

It just seems to me that no one is that interested in talking about code optimization and best practices right now. lol

I’m very interested in talking about this, but I’ve avoided this conversation on purpose until now. Here are some thoughts after considering everything here.

[*] I like to see all of the ideas develop in the community before I start committing to any action; listening to all these ideas before posting is an example, and I’d apply the same approach to adopting and publishing official best practices.
[*] I believe best practices come from experience, and from as wide a range of experience as possible. Our initial best practices will evolve from the work of those early adopters who begin to do more development with the framework, and continue to mature from there.
[*] I believe there is a big line between best practices for coding and ’optimisation’ as you call it, and setting up standards for submitting code. We can certainly provide a header documentation format standard that can be required for code submitted for official MODx approval, and this could be in phpdoc form, so as to allow automation within the framework for things like presenting snippet parameters and value options when adding a snippet tag to a content area.
[*] I will not champion code formatting standards. Everyone has a different idea of what the best style is, and I’d like to keep it that way and avoid the whole argument. Been there; done that.
[*] Imparting knowledge on the proper way to code, optimize code, format code, or any other thing with code in PHP is not the scope of the MODx project; documenting how PHP can be used or is constrained within MODx is, but I do not believe there is any need for coding standards beyond providing developer information on what can and can’t be done in the various code components (snippet, plugin, module, @EVAL, etc.). That is the purpose of developer documentation, which already exists, though needs to be developed in more depth.
[*] Instead of adopting a bunch of rules that can more often than not, constrain the creativity of certain developers, I’d rather see a few simply stated principles be published to inspire the evolution of best practices based on what works for a wide range of situations and developer styles.
[*] It’s early yet in our development, and I still find new ’best practices’ every day. I think what we need is a knowledge base of best practices, presented in the form of case studies. As more case studies appear and other feedback comes through the existing channels, we will start to see the clear principles of development and best practices for all the things you can do with MODx migrate it’s way into the documentation; and not just the PHP-related areas, because MODx is about so much more than modules, plugins, and snippets.

Just some quick thoughts off the top of my head. But there are lots of good ideas here we can develop into a first set of best practices to be presented in the documentation as appropriate.

I like to see all of the ideas develop in the community before I start committing to any action; listening to all these ideas before posting is an example, and I’d apply the same approach to adopting and publishing official best practices.

I agree with you.

I will not champion code formatting standards. Everyone has a different idea of what the best style is, and I’d like to keep it that way and avoid the whole argument. Been there; done that.

Me so. Code formatting is not an obligation but I think is a good practice to read code and to add modification if submitter does not continued developement of this ressource. The first goal of this, it’s to avoid error : for example try to modify a string whereas it is an array. But I realize it not easy to make it. I am of your opinion; let us forget it.

Imparting knowledge on the proper way to code, optimize code, format code, or any other thing with code in PHP is not the scope of the MODx project; documenting how PHP can be used or is constrained within MODx is, but I do not believe there is any need for coding standards beyond providing developer information on what can and can’t be done in the various code components (snippet, plugin, module, @EVAL, etc.). That is the purpose of developer documentation, which already exists, though needs to be developed in more depth.

I think is necessary to indicate this good practices to avoid modx become heavy when running. Maybe, it is not the good topic... Can you indicate me where is the developer documentation ? I can’t find it. Thanks.

Instead of adopting a bunch of rules that can more often than not, constrain the creativity of certain developers, I’d rather see a few simply stated principles be published to inspire the evolution of best practices based on what works for a wide range of situations and developer styles.

The principal goal of this rules (for me) is to permit a great evolution of Modx with ressources. Many of recomendation that I write is based on my experience of Modx. Many problems that I found is with localization but too hardcoded string in all ressources, php not simplty optimised, functions which not affected by other functions (like setlocale). Actually, ressources are not much evolutive with localization. It is a real problem.

I think what we need is a knowledge base of best practices, presented in the form of case studies. As more case studies appear and other feedback comes through the existing channels, we will start to see the clear principles of development and best practices for all the things you can do with MODx migrate it’s way into the documentation; and not just the PHP-related areas, because MODx is about so much more than modules, plugins, and snippets.

I think also that Modx is not only modules, plugins, and snippets. But it is an increasingly large part of modx.
Case studies is a good idea, and I think it’s necessary. But it’s not easy to find this or that in the forum. More case studies appeare, more found is difficult. So, I think a topic with good pratices is very important for help everyone to make code easly readable and performant as far as possible.
In France, we have an expression "Usine à gaz" ("Gas works"). This is want to say "oh! this is dangerous! it is ready to explode !". An example of this (it is not a critical) is PHPNuke. It was a great application but with the time, addition after addition, it is became too much heavy. I am afraid that Modx become like PHPNuke because of ressources.
I think "Good practices" and "Cases studies" are complementary and required.

But there are lots of good ideas here we can develop into a first set of best practices to be presented in the documentation as appropriate.

Thanks a lot. Comments and different opinions are already welcome.

Nice input.

To be honest, I’m in no position to talk about best-practices using PHP, as well as MODx. I’m just happen to be a computer science student who knows a little bit about coding, and have a really hude interest in web development project. I learned PHP while it’s still in version 3 for a month or so. I use ASP .Net before I join MODx community for this past few months, and I had built a framework using that .Net framework, and I’m an unsatisfied programmer with the current bloated system that causing the system to run slow in older machine, even though there are a lot of good things on .Net framework as well. I soon realize that the development on .Net framework is relying too much on their visual studio IDE, which causing me a lot of headache to learn that super-power IDE. So here I am, learning from scratch about all the PHP language, and if you guys would excuse me, all the past conversation that we have is basically emphasize too much on the PHP language itself, because I want to know more about PHP language, so without realizing it, I drag guillaume to explain it further for my own advantage.

So to cut the story short, here is my opinion.

I totally agree with the concept of not forcing coding style to each developers, even though I’ve never been involved coding in a team, which all developers got their own coding style and etc, but as the core developer, I would prefer to read my code in my own coding style, and the additional developers need to be able to adapt to that coding style. I think this is the number one rule for programmer, to be able to accept other people coding style, and in fact use that coding style in working on that code.

Having a simple list of things that need to be avoided when coding in PHP, and a specific reference articles that developers able to read before starting to code will be awesome, even though it’s unrealted to MODx, but we can help all those programmers who are starting to use PHP to know it (a good example will be me). We don[’t have to maintain it extensively, but having it as a reference link will be great don’t you guys agree with me?

Talking about imparting knowledge, I’m 100% agree to that. MODx can be seen from 2 different point of view. The first one will be from the end user, as a full-fledge content management system, while on the side, it can be seen as a full-fledge content management framework for advanced users. By imparting knowledge, the documentation that we have right now needs to be divided into two. The first documentation will be composed for the end users and all people starting with MODx, while the other documentation will be aiming towards the developers documentation. Basically drupal documentation serve as a good example for us to see the importance to differentiate between this. If we have the documentation separated, we can start having an impartation of knowledge from developers’ point of view and end users’ point of view. With this, it won’t make the documentation for the end users too complicated, and it won’t make the developers’ documentation too easy and uncomplete, and causing a new developers got confused on where to start building something on top of this framework.

Another important thing will be the folders structured and commenting structure. I believe this won’t cut down the creativity of the developers, instead it will increase consistency between each resources releases, and making it a lot easier to be used by other people. The idea of having the commenting to be parsed by phpdoc is a great idea. I’ve tried to follow the phpdoc guideline in my commenting system, but I still find it kinda hard to use, considering that the commenting doesn’t have a clear formatting to be read on the code, so most of the time, I ended up coming up with my own commenting system that looks like phpdoc format, but it’s not.

Anyway, more input discussion will be awesome.

because I want to know more about PHP language, so without realizing it, I drag guillaume to explain it further for my own advantage.

I think that it is very with your honor

to be able to accept other people coding style,

Yes. It’s because I propose to forget the coding style.

If we have the documentation separated, we can start having an impartation of knowledge from developers’ point of view and end users’ point of view. With this, it won’t make the documentation for the end users too complicated, and it won’t make the developers’ documentation too easy and uncomplete, and causing a new developers got confused on where to start building something on top of this framework.

Yes. I’m a PHP developer so always I view the 2 parts in the same time. I can’t dissociate the 2 documentation. If some can make it, I will be happy.

I’ve tried to follow the phpdoc guideline in my commenting system, but I still find it kinda hard to use, considering that the commenting doesn’t have a clear formatting to be read on the code,

Yes it is. I have try also for an enormous project because it was necessary. But I can’t do for small : it’s difficult and not very human readable. I think is a very good idea but I prefered to leave everyone make their own comments properly and clearly than bad comments cause of phpdoc.

The rule of thumb in drawing a clear separation line between both documentations is to make sure that everything relate to coding using php will be part of developers’ documentation.

For end users

• Installation/upgrade
• general explanation of chunks, snippets, modules, plugins, templates
• explanation on MODx tag and it includes site setting tag and server processing tag (mysql time and php time).
• general explanation on how to use TV with all the provided widget and binding.
• case study in setting up MODx for specific usage using the available resources
• installing resources and detailed explanation on how to use resources, such as detailed explanation on how to use official MODx resources and etc.
• FAQ for general support
• best practices to use MODs features/resources/capabilities to create a site

For developers

• API reference
• creating new module, snippets, or plugins
• in depth explanatin of the power of each unique features, such as the use of TV to be integrated with chunk, snippets, and plugins to achieve something like shopX for example and etc.
• Database and system architecture, so we know what to do when doing some hack in improving the system
• best practices reference on PHP scripting language

More can be added to the list, but for now, I think this will be enough clear picture for us grasp the difference between both of the documentation

It is so true with what Jason said about the coding style and I appreciate that openmindness!

Someone people using coding style for the purpose of easy documentation like this link here:
http://www.devshed.com/c/a/PHP/Writing-SelfDocumenting-PHP-Code/1/

Over the year I learn this basic rule of thumb:
. If I write the code from scratch I my own coding style
. If I modify someone else code I will try to adapt the coding style already there so that I will not look too foreight.

Over the year I learn this basic rule of thumb:
. If I write the code from scratch I my own coding style
. If I modify someone else code I will try to adapt the coding style already there so that I will not look too foreight.

It’s really good. I had not propose to obligate coding style but recomand it for better reading. Now, I realize it is a bad idea (I acknowledge that I will be the first "disturbed"). Honestly, I propose to forget this (stupid) idea of coding style

Chanh, thanks for your comment.

I would agree that coding styles vary according to a person’s taste and education. But I do think there should be certain "standards", especially in the head of the code. A comment block that follows a general rule, with a brief explanation of what the snippet does, and a list of optional or required arguments, with suggested values (0|1, true|false, etc) and defaults, if applicable. This way users will be familiar with how the usage instructions of the snippet will appear in any snippet.

I also think some coding rules should apply, such as using the MODx DBAPI, would be helpful to keep things working smoothly, even if changes are made to the MODx core or the DBAPI, the interface would remain the same.

It would also be very nice if everyone could use the same general arguments for the same purpose, having to figure out if the snippet uses &id= or &startDoc= or what??? to indicate the document to use as the base for the snippet’s operation is a real pain.