Diff: Best Practice / Coding Style

 Ownership:  rw-rw-r-- Garvin wheel
 Modified:  21 Feb 11, 10:19
 Modified by:  Garvin Hicking (Garvin)
Rev.:  4 (Old)
 
 Ownership:  rw-rw-r-- Garvin wheel
 Modified:  23 Dec 11, 13:28
 Modified by:  Garvin Hicking (Garvin)
Rev.:  5 (Current)


<toc>

+ %TITLE%

Everyone can contribute plugins or themes to Serendipity. We all gladly appreciate this. New contributors please simply come to the s9y.org forums and announce their work there. If people want to, they can get CVS accounts to manage their plugins and themes on Spartacus.

++ Coding Style for Templates

* Make sure that you only change template files you absolutely must. Serendipity can fallback to use default template files, so if you do not need to change the 'index.tpl' file for example, please simply do not provide that file.

<toc>

+ %TITLE%

Everyone can contribute plugins or themes to Serendipity. We all gladly appreciate this. New contributors please simply come to the s9y.org forums and announce their work there. If people want to, they can get CVS accounts to manage their plugins and themes on Spartacus.

++ Coding Style for Templates

* Make sure that you only change template files you absolutely must. Serendipity can fallback to use default template files, so if you do not need to change the 'index.tpl' file for example, please simply do not provide that file.

* If your templates needs a config.inc.php file or custom language files, please try to make those files as small as possible. Performance counts, and PHP code should only be used if the code in there is fit to be executed on each page visit.
* If your templates needs a config.inc.php file or custom language files, please try to make those files as small as possible. Performance counts, and PHP code should only be used if the code in there is fit to be executed on each page visit. You can disable smarty security through $serendipity['smarty']->security = false - but only do this, if you absolutely must due to custom use of unregistered PHP functions or modifiers or {php} calls.

* Please try to properly indent all of your HTML and CSS rules by using 4 spaces (not Tabs).

* Please try to be XHTML 1.1 Strict compliant. XHTML 1.0 Transitional is also alright, but HTML 4.0 should really no longer be used.

* Please try to make sure your template can be viewed in Mozilla Firefox, Microsoft Internet Explorer and if possible also properly in Opera, Safari and other "minor" browsers.

* If you provide foreign language files, also deliver the language files inside the "UTF-8" subdirectory of your template, and save them in UTF-8 encoding. Save all files using UNIX Linebreaks (\n) if possible.

++ Coding Style for Plugins

* Serendipity tries to use PEAR Coding Guidelines: ((http://pear.php.net/manual/de/standards.php)(PEAR Coding Standards)). Short version: Use 4 spaces, no Tabs and always indent your code properly. Always include { and }, also if optional.

* Try to use OO methods for the functionality your plugin requires. The abstracter your class methods, the easier it can be extended in the future.

* Only use event hooks that your plugin absolutely needs.

* Please try to properly indent all of your HTML and CSS rules by using 4 spaces (not Tabs).

* Please try to be XHTML 1.1 Strict compliant. XHTML 1.0 Transitional is also alright, but HTML 4.0 should really no longer be used.

* Please try to make sure your template can be viewed in Mozilla Firefox, Microsoft Internet Explorer and if possible also properly in Opera, Safari and other "minor" browsers.

* If you provide foreign language files, also deliver the language files inside the "UTF-8" subdirectory of your template, and save them in UTF-8 encoding. Save all files using UNIX Linebreaks (\n) if possible.

++ Coding Style for Plugins

* Serendipity tries to use PEAR Coding Guidelines: ((http://pear.php.net/manual/de/standards.php)(PEAR Coding Standards)). Short version: Use 4 spaces, no Tabs and always indent your code properly. Always include { and }, also if optional.

* Try to use OO methods for the functionality your plugin requires. The abstracter your class methods, the easier it can be extended in the future.

* Only use event hooks that your plugin absolutely needs.


* If your plugin emits a notable amount of HTML, please make use of bundled Smarty template files. Use the $serendipity['smarty']->fetch() method to load TPLs, and first check in the template directory for the .tpl file, and only as a fallback use the .tpl file in the plugin directory. To be able to use any directory for .tpl story, you need to temporarily disable Smarty's security through $serendipity['smarty']->security_settings[INCLUDE_ALL] = true. Save the current state in a temporary variable to restore it after the fetch() method. Since Serendipity 1.7, this is no longer necessary, but if your plugin should be compatible to older Serendipity versions you should provide this.

* Try to cache results that come from foreign URLs. If your plugins displays an RSS feed, it shouldn't be fetched each execution cycle of the plugin, but rather only every X minutes. Provide a configuration option to let the user configure his own caching period.

* Generally, try to save as much performance as possible. Avoid recursive function calls (if possible), try to make use of referenced variables ($eventData is one of those).

* Always abstract any output messages with language constants. Always include an english language file of your plugin.

* If you enhance functionality of the plugin, please add a file called "((Change Log))" documenting changes.

* If you want to write documentation for a plugin, write HTML markup and save it all in a *documentation_XX.html* file. XX is the code for the specific language. Save UTF-8 versions of the file in the UTF-8 subdirectory.

* If your plugin emits HTML code for buttons on the backend, always use the 'serendipityPrettyButton' class. And use a class, depending on the input type: "input_radio", "input_checkbox" or "input_button".

* If your plugin emits a custom menu item on the backend sidebar, please use an item like '<li class="serendipitySideBarMenuLink">'.

* If you bundle foreign code, make sure you indicate the right licensing of your plugins. By default, a s9y plugin is BSD licensed.

* If possible, try to avoid many small files. Spartacus can better be used with few larger files.

* If your plugin has foreign code dependencies, either include those in the plugin or make sure, your plugin does not bail out with a fatal error otherwise. It should always alarm the user what's missing.

* Only use SQL statements that work in PostgreSQL, SQLite and MySQL. Branch your SQL code, if different statements are required for different syntaxes. If your plugin needs a custom DB table, make sure you create it using serendipity_db_schema_import().

* Security: Try to keep your plugin free from XSS and SQL injection. Always use serendipity_db_escape_string() on POST/GET-variables when you store them in the database, always add htmlspecialchars() when you output a POST/GET-variable. If your plugin uses administrative tasks in the backend, make sure you use the serendipityFormToken() functions to protect against XSRF.

* *Closing Words*: Take a look at existing plugins. What has worked in the past, might work out for you as a draft for your own plugin.
* Try to cache results that come from foreign URLs. If your plugins displays an RSS feed, it shouldn't be fetched each execution cycle of the plugin, but rather only every X minutes. Provide a configuration option to let the user configure his own caching period.

* Generally, try to save as much performance as possible. Avoid recursive function calls (if possible), try to make use of referenced variables ($eventData is one of those).

* Always abstract any output messages with language constants. Always include an english language file of your plugin.

* If you enhance functionality of the plugin, please add a file called "((Change Log))" documenting changes.

* If you want to write documentation for a plugin, write HTML markup and save it all in a *documentation_XX.html* file. XX is the code for the specific language. Save UTF-8 versions of the file in the UTF-8 subdirectory.

* If your plugin emits HTML code for buttons on the backend, always use the 'serendipityPrettyButton' class. And use a class, depending on the input type: "input_radio", "input_checkbox" or "input_button".

* If your plugin emits a custom menu item on the backend sidebar, please use an item like '<li class="serendipitySideBarMenuLink">'.

* If you bundle foreign code, make sure you indicate the right licensing of your plugins. By default, a s9y plugin is BSD licensed.

* If possible, try to avoid many small files. Spartacus can better be used with few larger files.

* If your plugin has foreign code dependencies, either include those in the plugin or make sure, your plugin does not bail out with a fatal error otherwise. It should always alarm the user what's missing.

* Only use SQL statements that work in PostgreSQL, SQLite and MySQL. Branch your SQL code, if different statements are required for different syntaxes. If your plugin needs a custom DB table, make sure you create it using serendipity_db_schema_import().

* Security: Try to keep your plugin free from XSS and SQL injection. Always use serendipity_db_escape_string() on POST/GET-variables when you store them in the database, always add htmlspecialchars() when you output a POST/GET-variable. If your plugin uses administrative tasks in the backend, make sure you use the serendipityFormToken() functions to protect against XSRF.

* *Closing Words*: Take a look at existing plugins. What has worked in the past, might work out for you as a draft for your own plugin.

Legend

 Removed 
 Changed 
 Added