Programmers Guidelines
System Development
Recommended Development Tools
Write packages in plain .m-files, no programming in .nb notebook-files. m-files can be edited as package files in the
Mathematica FrontEnd, still providing some of the convenient notebook features (e.g. sectioning, collapsing cell groups, etc.).
As the preferred development environment, however, we recommend the
Wolfram Workbench.
Running Theorema through the Workbench
Importing the project
The directory obtained from the git-repository is the base directory of a Workbench-project. You can import it into the workspace through the menu "File - Import ... - Existing Projects into Workspace" and then just follow the instructions. The project will be configured automatically, no settings need to be adjusted.
Deactivate auto workspace refresh in the workbench preferences
In the Workbench preferences - General - Workspace uncheck "Refresh automatically" (checked by default). Otherwise, in case you have Theorema notebooks in the workspace (e.g. as part of the documentation) the workbench will permanently refresh when Theorema creates new files in a notebooks's auxiliary directory e.g. during a computation, which in turn will always reload the Theorema system.
Running Theorema from within the Workbench
The best way to run Theorema from within the Workbench is to simply choose "Run ..." from the Run-menu. Theorema will load and a test notebook will appear, which you can ignore for most of the time. The
Theorema commander starts and you can open any Theorema notebook or create a new one from there.
We do not recommend to open existing Theorema notebooks or to create new notebooks using the native
Mathematica commands for opening and creating notebooks because this may lead to troubles with the stylesheets. For the same reason we do not recommend to launch Theorema using "Run As ..." or "Debug As ..." on an existing notebook.
Language Dependency
Language dependent strings (help messages, button labels, menu entries, etc.) should be defined in the corresponding "LanguageData" packages. Use the Theorema-function
translate accordingly. It will use the language chosen in
$TmaLanguage, which is set in the Preferences-activity in the
Theorema commander.
For the Programmer
When you add a new entry in one of the "LanguageData" packages (typically in one of the "English.m"), then please
- note that the entries are sorted and insert the new entries in the appropriate order
- copy the line to all other language files present even if you cannot provide the proper translation (in which case you just leave it in the original language, e.g. English). Collect the untranslated stuff near the end of the file. There should be a block of already translated entries (sorted) near the beginning of the file and clearly seperated from that a block of still to be translated entries (unsorted) near the end of the file. Otherwise it will be tedious for a translator to find out, which translations are still missing.
For the Translator
Suppose you are able to translate language "A" (e.g. English) to language "B". When you provide translations for your language "B", then walk through all "LanguageData" directories and do the following:
- If "B.m" does not yet exist, copy the package "A.m" to "B.m".
- If a directory "A" exists but no directory "B", then create a directory "B" and copy the content of "A" into "B".
Programming
Naming Conventions
Function names: lower case, no special characters except $, upper case on word boundaries, e.g. openComputation.
Global variables: start with $.
Data structures: short names, all upper case, ending in $, e.g. VAR$.
Unevaluated fresh names (in order to avoid evaluation by
Mathematica): upper case, ending in $TM, e.g. Plus$TM.
Spacing and Indentation
In general, opening brackets "[" and commas "," are followed by a blank. Rare exceptions allowed, e.g. f[1], Module[{x, y}, ...].
Multiline expressions indented as follows:
If several brackets or braces appear in a row, we prefer
multiline[{
body1,
body2
}]
multiline[
{
body1,
body2
}
]
Package Dependencies
Usually, if package A depends on package B, package A is set up using
so that symbols exported by B are visible in A. In order to keep the ContextPath "clean", we use so-called "private package import"
which also makes symbols exported by B visible in A, but will not leave "B`" in the ContextPath after loading package A.
Moreover, we use one central package Theorema`Common` for shared symbols. All symbols that need to be used across packages should be defined there, and all packages that need symbols from other packages just use
This gives a flat package hierarchy that can easily be maintained.
Default Case for Pattern Definitions
For functions that are defined through various patterns, provide a default case that will match if all (intended) cases fail.
This will interrupt program execution and tell that 'f' has been called with unexpected arguments 'args'. This will facilitate debugging.
Use Assert
Assert is a new feature in
Mathematica 8, which allows to test assumptions that interrupt program execution in case it is detected that the test fails.
Organization
Theorema editor
Every file names a
Theorema editor (TE) in the file's header. The TE is the person through which modifications to that file can go into the common repository. Technically, this means that changes to a file, which is not edited by yourself, should be made in a separate branch in the revision control system, from which the TE can pull the changes and forward them into the common repository.