Development guidelines

== Porting checklist ==

• Are there any camelCase functions left?
• Are all examples in scripts. Do they work?
• Should we rename anything? Now is the chance to do it.
• Are all the name changes in fixes/?
• If you renamed anything, you have to rename it also in 2.5 testing scripts, in fixes and in Orange 2.5 code. Orange 2 code should be left as is.
• Do you get any Deprecation Warnings? (Python 2.7 users should enable them python -Wall)

== Documentation ==

=== Overview ===

Avoid conversational style that was common in previous documentation (for example, rewrite sentences containing "you"). Avoid future tense; use present instead (for example, "classifier will be used" -> classifier is used").

Examples of documentation that is OK:

• http://orange.biolab.si/doc/reference/Orange.data.variable/
• http://orange.biolab.si/doc/reference/Orange.feature.scoring/
• http://orange.biolab.si/doc/reference/Orange.classification.knn/

Documentation checking stories: #882, #933, #939, #966, #986.

=== Code samples ===

Each code sample should be a python script and should only be (perhaps partially) referenced in the file. Never copy the code into the documentation. This also holds for most of the one-liners, as code in separate files is much easier to test and fix when interface changes.

Import just '''Orange''' and use full paths. Avoid exceptions. Never import *.

Use '''download''' to link downloadable files, for example

See :download:`this example script <../example.py>`.

Delete "uses dataset.tab" from introductions to examples, because data sets from the documentation can now be loaded easily. Decide whether the .py file needs to be linked yourself.

=== Referencing other classes, functions, methods ===

If it is clear what are writing about, use shorter form, for example, {{{:obj:~Orange.classification.rules.X}}} instead of {{{:obj:Orange.classification.rules.X}}}.

== Coding ==

=== CamelCase to underscore_separated ===

Names of methods, functions, (object) attributes and keyword attributes of functions should all be underscore_separated. Abbreviations should also be in lower case. For example, we should rename AUCWilcoxon to auc_wilcoxon (and not AUC_wilcoxon).

For now, all C++ code is accessible both with CamelCase and underscore separated [wiki:Orange25/C++CamelCase (detailed description)]. Python code should be converted with [wiki:Orange25/NameDeprecationDecorators name deprecation decorators] (see the page for an example).

=== Refactoring tool ===

Do forget to update the [wiki:Orange25/RefactoringTool refactoring rules].

=== Output of models ===

Output of learning models. Learning models (classifiers, regressors) need to have __str__ defined. If it needs a parameter, also add a to_string method, but __str__ should still return something. For example

data = Orange.data.Table("titanic")
c = Orange.classification.tree.TreeLearner(data)
print c #prints out the model
print c.to_string(max_depth=1) #with some special formatting

=== Model plotting ===

The most typical one should be plot(), but if there are multiple different plots, prefix them with plot_, for example plot_dendrogram.

=== Data set naming ===

In documentation, do not use '''table'''. Name of the data set is preferred (but just '''data''' is also acceptable), so write:

iris = Orange.data.Table("iris")

In code, use data.

=== General coding convention ===

General coding conventions can be checked using [http://pypi.python.org/pypi/pylint pylint] (it checks many other things too, like unused variables ...). You can install it using pip, easy_install or your favorite package manager. There is a pylintrc configuration file in repository root - pylint will use it automatically if run from within the repository structure.

Example:

pylint Orange/classification/tree.py

To filter out only naming conventions

pylint -rn -iy Orange/classification/tree.py | grep C0103