Coding conventions

From semantic-mediawiki.org
Jump to: navigation, search

SMW and many of its extensions stick to strict naming conventions and code styles based on the MediaWiki coding conventions. The following guidelines apply to SMW, but can often be adopted to other extensions by just changing the prefix SMW.

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".

src vs. includes folder

"... are classes in the folder “src/”, which follow PSR-4 layout, and in the folder “includes/”, which seem to follow the classic MediaWiki layout ..."1

"src/" follows PSR-4 and due to legacy reasons classes in "includes/" have no or very rudimentary test coverage. Once a class meets certain criteria (one of which is sufficient test coverage among others) it will be moved to "src/" with the objective to remove "includes/" in future.

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

Class annotations

The @private annotation for a class is indicating a solely restricted use within the SMW-core code base and even though a class might provide public access methods, it SHOULD NOT be expected that the class itself or its methods will be available during or after a specific release cycle.

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 MediaWiki coding conventions. Please be sure to read this document.

  • Do not use a closing "?>" tag in your source files. It is a source for errors that is not needed in included files.
  • Document all your code (see below for details)!
  • Avoid single lines of code becoming too long.
  • Indenting of program blocks is done with tabulators, not with spaces. All program blocks are indented.
  • All indented program blocks should be enclosed with { and }, even if they have one line only.
  • Using in-line conditionals for value computations is fine ("condition?thenvalue:elsevalue").
  • 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.
  • Value constants like true, false, and null are always written lower case.
  • 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_".
  • Resources loader modules registered with SMW are generally named with a prefix such as ext.smw.<...>, ext.srf.<...>, ext.semanticforms.<...>

Code layout and indenting

No general code layout for SMW's JavaScript has been proposed or implemented yet.

  • JSHint can help detect errors and potential problems in JavaScript code

Source documentation

The GIT-version must be deployable at all times. Update INSTALL whenever needed! Provide update instructions and methods in case of incompatible changes.

  • Every class and function must have a short documentation, enclosed in "/** ... */". These blocks are used to generate the MediaWiki code documenation via doxygen.
  • Use @since possible to indicate the version in which the function or field was added. Also do this for hooks.
  • Use type hinting where possible. It is important to do this in new code that can be inherited, as deriving classes won't be able to use type hinting when this is not done in the base class.
  • Use "@todo" and "@bug" in doxygen comments to keep track of to-dos and bugs directly within the code.
  • Complex code and hacks should be documented with C-style line-comments ("// ...").
  • User documentation (mostly for SMW_Settings.php) should be documented with Shell-style line-comments ("# ...").
  • Implementations that affect usage must be documented in the online user documentation before release.
  • Changes that are relevant to users, administrators, or third-party developers must be mentioned in the file RELEASE-NOTES. A short note is enough.


References

  1. ^  Code structure "I’ve noticed that you have two parallel structures in your code base..."