Programmer's guide to SMW
From semantic-mediawiki.org
Developers who want to support SMW development or develop extensions to SMW can use a number of resources to get started. Of course, it is strongly recommended to be familiar with the usage of SMW as well.
Contents |
Getting started
When switching from a user to a developer of SMW, you should also change the configuration of your testing wiki to ensure that you do not overlook possible errors or problems (especially those created by your own code). Please read about how to debug MediaWiki, in particular the section about PHP error reporting. All MediaWiki extensions are expected to run without issuing any PHP notices!
Also take a moment to familiarise yourself with the MediaWiki resources for developers.
Code documentation
SMW and its extensions try to provide thorough code documentation as part of their program files. An API documentation is automatically generated from this data:
This documentation encompasses SMW, Semantic Result Formats, Semantic Forms, Semantic Drilldown and Semantic Google Maps. It is rebuilt every day from the current contents of SVN. Further extensions can be added to this documentation if they relate to SMW, are hosted in MediaWiki SVN, and use naming conventions that prevent confusion with the other extensions (which use prefixes SMW, SRF, SF, SD and SGM).
Programming style
SMW and many of its extensions stick to strict naming conventions and code styles. The following guidelines apply to SMW, but can often be adopted to other extensions by just changing the prefix SMW.
PHP settings
- The required version of PHP is found in INSTALL.
- All developers need to have all errors, warnings, and notices in PHP switched on. Edit your file php.ini to contain error_reporting = E_ALL and remove any other statement of this kind.
- Edit your php.ini to contain allow_call_time_pass_reference = Off.
- Your final code should never create any of the respective messages.
Files and folders
- Files in the project are all prefixed with "SMW_". In general, it should be possible to put all the project files into MediaWiki's include folder without getting name conflicts.
- Folders are usually not changed or created. The only exception are Special pages which all reside in their own folders below the folder "specials".
Encoding
- All files need to be stored as UTF8! This is absolutely crucial.
- All line endings must be UNIX-style. Set your auto-props!
PHP
- Do not use a closing "?>" tag in your source files. It is a source for errors that is not needed in included files.
Naming conventions
In general, all names are written CamelCase, although methodNames and variableNames typically start with lower case letters.
- Classes are prefixed with "SMW" if they are accessible globally. Class definitions that are encapsulated in methods do not have a prefix. Another exception are classes for Specials which should be named after the special, as is common in MediaWiki.
- Functions are prefixed with "smwf" if they are accessible globally. Class functions do not have a special prefix.
- Variables are prefixed with "smwg" if declared globally. Variables in a class do not have a special prefix. Local variables in functions typically do not CamelCase, but use "_" if any separation is needed.
- Constants are written ALL_CAPS with underscores as internal separator, and are to be prefixed with "SMW_", as e.g. in "define('SMW_SP_HAS_TYPE', 1)".
Code layout and indenting
In general, code layout is guided by the usage in MediaWiki.
- Indenting of program blocks is done with tabulators, not with spaces.
- Spaces around "=" (variable assignment) and all operators, including "." (string concatenation), are recommended.
- In conditionals, conjunctions and disjunctions should be written as && and ||, respectively, not as and and or.
- Class-members should be declared protected or private if applicable. The use of public is not required, since it is the default (other than for variables, where public is to be preferred over var).
- Use the keyword static where appropriate. Consider changing global functions into static class functions.
- When you finish some task, take some time to remove unused debug-statements, functions, and local variables from your code!
JavaScript
Naming conventions
In general, all names are written CamelCase, although methodNames and variableNames typically start with lower case letters.
- Functions are prefixed with "smw_".
- Variables mostly don't adhere to any naming conventions, but global variables should have the prefix "smw_".
Code layout and indenting
No general code layout for SMW's JavaScript has been proposed or implemented yet.
Documentation
The SVN-version must be deployable at 90% of the time. Update INSTALL whenever needed! Provide update instructions and methods in case of incompatible changes.
- Every class and function should have a short documentation, enclosed in "/** ... */". These blocks are used to generate the MediaWiki code documenation via doxygen.
- Complex code and hacks should be documented with C-style line-comments ("// ...").
- User documentation (mostly for SMW_LocalSettings) should be documented with Shell-style line-comments ("# ...").
- Implementations that affect usage must be documented in the online user documentation before release.
- Use "TODO" to introduce to-do items.
