Mercurial > projects > mde

annotate codeDoc/policies.txt @ 24:32eff0e01c05

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Only locally-changed options are stored in user-config now. Log levels revised. Options sub-classes are handled more generically and can be added without changing the Options class. Options changed at run-time are tracked, and on exit merged with user options and saved. Revised log levels as set out in policies.txt and as used in code. committer: Diggory Hardy <diggory.hardy@gmail.com>
author Diggory Hardy <diggory.hardy@gmail.com>
date Thu, 27 Mar 2008 16:15:21 +0000
parents 5f90774ea1ef
children 611f7b9063c6
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
17
5f90774ea1ef Applied the GNU GPL v2 to mde.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 15
diff changeset
1 --- License ---
5f90774ea1ef Applied the GNU GPL v2 to mde.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 15
diff changeset
2 Part of mde: a Modular D game-oriented Engine
5f90774ea1ef Applied the GNU GPL v2 to mde.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 15
diff changeset
3 Copyright © 2007-2008 Diggory Hardy
5f90774ea1ef Applied the GNU GPL v2 to mde.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 15
diff changeset
4
5f90774ea1ef Applied the GNU GPL v2 to mde.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 15
diff changeset
5 This program is free software; you can redistribute it and/or modify it under the terms of
5f90774ea1ef Applied the GNU GPL v2 to mde.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 15
diff changeset
6 the GNU General Public License, version 2, as published by the Free Software Foundation.
5f90774ea1ef Applied the GNU GPL v2 to mde.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 15
diff changeset
7
5f90774ea1ef Applied the GNU GPL v2 to mde.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 15
diff changeset
8 This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
5f90774ea1ef Applied the GNU GPL v2 to mde.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 15
diff changeset
9 without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
5f90774ea1ef Applied the GNU GPL v2 to mde.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 15
diff changeset
10 See the GNU General Public License for more details.
5f90774ea1ef Applied the GNU GPL v2 to mde.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 15
diff changeset
11
5f90774ea1ef Applied the GNU GPL v2 to mde.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 15
diff changeset
12 You should have received a copy of the GNU General Public License along
5f90774ea1ef Applied the GNU GPL v2 to mde.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 15
diff changeset
13 with this program; if not, write to the Free Software Foundation, Inc.,
5f90774ea1ef Applied the GNU GPL v2 to mde.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 15
diff changeset
14 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */
5f90774ea1ef Applied the GNU GPL v2 to mde.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 15
diff changeset
15
5f90774ea1ef Applied the GNU GPL v2 to mde.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 15
diff changeset
16
5f90774ea1ef Applied the GNU GPL v2 to mde.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 15
diff changeset
17
15
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
18 --- Introduction ---
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
19 This is a collection of all coding policies for the mde engine as a whole. Policies for individual packages should be put in the individual package directory or elsewhere.
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
20
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
21 These are principles, not cast-iron rules, which I (Diggory Hardy) generally try to adhere to. If any other programmers have better principles to apply over these rules, they may do so for their own coding providing they have a good reason (i.e. not simply wanting to be a little different).
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
22
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
23 A warning: I have several times changed my mind about items I've written here. So don't expect all existing code to conform, and if you feel that a principle listed is not a good idea don't think you have to conform to it.
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
24
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
25
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
26
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
27 +++ CONTENTS +++
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
28
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
29 0 Introduction
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
30
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
31 1 Coding conventions
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
32
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
33 2 Documentation
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
34
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
35 3 Package design principle
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
36
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
37 4 Initialisation / cleanup
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
38
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
39 5 Testing
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
40
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
41 6 Logging
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
42
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
43 7 Exceptions
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
44
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
45 8 Translating strings
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
46
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
47
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
48
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
49 --- Coding conventions ---
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
50 Mostly stick to those provided in the D specification.
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
51
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
52 Indentation: Preferably indent with four spaces and align comments either with tabs or spaces. If you do use tabs, use a tab-width of 8.
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
53
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
54 Long lines: Aim to break long lines at around 100 chars (particularly with documentation); this isn't essential but provides a good guide and keeps text looking reasonable. With code, however, breaking lines doesn't always produce better-looking code so just try to keep it neat.
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
55
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
56 Identifiers: as for the D spec, use descriptive words for identifiers, although try to keep them from being overlong. Use capital letters to show separate words, not underscores. E.g.: file, readFile; not: rdFile, read_file, readFileUsingMyMethodNow. Use CAPS for consts (with underscores as word separators), Capitalisation for class/interface/struct/union names, smallLetters for variables and class instances.
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
57
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
58 Module/file names: If the module corresponds directly to a single class, use the class name with correct Capitalisation as the module name. Otherwise, preferably use lower case. Always use the correct case when importing a module to keep code portable.
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
59
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
60 Spelling (within code): I am not going to stipulate British/American/other spellings, but keep to good English and use some consistancy (e.g. don't use both "defense" and "instance" together, unless unavoidable due to existing code).
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
61
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
62
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
63
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
64 --- Documentation ---
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
65 Documentation falls in to the following four categories:
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
66
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
67 Source file comments: Code comments only aimed at yourself or other programmers.
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
68
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
69 Source file DDoc: Documentation of the general working of modules, function purposes, syntaxes and operations, enums, classes, etc. Often only for public items. Also mostly only relevant to programmers.
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
70
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
71 codeDoc directory: For large amounts of documentation on the general working/principle/whatever of a module/package or mde in general. Directory hierarchy should mirror that of the source directory and files should have appropriate names and extensions (.txt if plain text). The most important difference between the codeDoc and doc directories is that information in codeDoc is only aimed at programmers, wheras information in doc is aimed at all users.
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
72
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
73 doc directory: Documentation aimed at the end user covering building, running, modding (excluding by programming), etc. Files should be appropriately named with an appropriate extension (.txt for plain text). Documentation regarding modding should be in a "modding" subdirectory. Documentation regarding translating may also be added.
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
74
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
75
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
76
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
77 --- Package design principle ---
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
78 Use a separate package for each module of the engine. In most packages where there is only one module (file) imported by other parts of the engine, that module should have the same name as the package and be designed to have a standardised interface to the package so that the package could be replaced with another as a drop-in replacement (written with the same interface). Of course in many cases it may not be possible to swich one package for another quite this easily, but holding to this principle should at least minimise the amount of work necessary when doing so.
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
79
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
80 Module imports: don't use public imports much, although for importing interfaces it may make sense. Use static/renamed/selective imports when importing a module containing a lot of module-level symbols unless it is a very closely related module.
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
81
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
82 Chain dependancies: If at all possible, avoid chain dependancies (e.g. use interfaces). Chain dependancies can cause many problems.
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
83
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
84
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
85
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
86 --- Initialisation / cleanup ---
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
87 This can be done in two ways:
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
88
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
89 mde.Init: This class is designed to handle all but the simplist startup and cleanup code, and thus allow it to be threaded where appropriate and allow user feedback of loading progress.
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
90
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
91 static [~]this(): Use of static CTORs/DTORs should be limited to very small operations which can definitely be run safely at this stage.
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
92
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
93
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
94
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
95 --- Testing ---
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
96 Testing should, as far as reasonably possible, be done by unittests, defined either in the appropriate module or another module. Any modules containing unittests must be imported by test.mdeTest.
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
97
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
98 Unittests must be wrapped in "debug(mdeUnitTest)" statements. (These may also be used to wrap imports and "static this()" only needed by the unittest.)
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
99
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
100 Unittests (last block in the module where multiple unittest blocks are used) should end with:
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
101 logger.info ("Unittest complete.");
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
102 No more logging should be needed, since if it fails whoever runs the unittest will know about it, and logging messages cannot be used to tell how complete the unittesting is. These messages just confirm that the unittests ran really.
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
103
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
104
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
105
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
106 --- Logging ---
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
107 Logging should be handled by tango's Logger class. A logger with the name of the form mde.package.module or mde.package.module.X where X is a symbol within the module should be used for each module.
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
108
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
109 In general the levels should be used as follows:
24
32eff0e01c05 Only locally-changed options are stored in user-config now. Log levels revised.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 17
diff changeset
110 Trace Where desired for debugging, and only compiled in debugging mode (i.e. wrap with debug).
32eff0e01c05 Only locally-changed options are stored in user-config now. Log levels revised.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 17
diff changeset
111 Info Sparingly, for informational purposes. Should not be used repetitively (within loops, etc.). Not for reporting unexpected behaviour or tracing program's running, except to the degree an end user may want. Also for unittests. Temporarily for reporting information to the user, until the GUI can be used instead.
32eff0e01c05 Only locally-changed options are stored in user-config now. Log levels revised.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 17
diff changeset
112 Warn For when something unexpected happens which is not necessarily an error (although could be).
32eff0e01c05 Only locally-changed options are stored in user-config now. Log levels revised.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 17
diff changeset
113 Error For anything which is definitely an error but not fatal.
32eff0e01c05 Only locally-changed options are stored in user-config now. Log levels revised.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 17
diff changeset
114 Fatal For errors directly (i.e. definitely) ending the program.
15
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
115
24
32eff0e01c05 Only locally-changed options are stored in user-config now. Log levels revised.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 17
diff changeset
116 For all levels except trace, messages should if possible be understandable to end users, while (for warn and above) including enough information to fix the problem when it is due to data files rather than code.
15
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
117 Thus:
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
118 Trace output should only be available when compiled in debug mode.
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
119 When run by an end-user (with info-level logging enabled),
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
120 • info messages normally occur and should be understandable to end users;
24
32eff0e01c05 Only locally-changed options are stored in user-config now. Log levels revised.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 17
diff changeset
121 • warn messages may occur, and may indicate problems;
32eff0e01c05 Only locally-changed options are stored in user-config now. Log levels revised.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 17
diff changeset
122 • error messages indicate that something is definitely wrong (even if it only has a minor effect on the program as a whole);
15
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
123 • fatal messages indicate a problem preventing the program from running.
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
124
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
125 Log/exception messages can be divided into two categories: those aimed at end users or modders and those only aimed at developers. A short string, either a brief English message or just a code, should be defined in the code, which can either be translated to a full message by I18nTranslation or output directly. The code string need not be a long description since it can be looked up in the code.
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
126
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
127
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
128
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
129 --- Exceptions ---
24
32eff0e01c05 Only locally-changed options are stored in user-config now. Log levels revised.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 17
diff changeset
130 Exceptions should only be used for errors (see comment on log levels above). Thus when an exception is caught, by definition an error occured.
15
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
131
24
32eff0e01c05 Only locally-changed options are stored in user-config now. Log levels revised.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 17
diff changeset
132 Thrown exceptions should, where documented, be documented via the logger.
32eff0e01c05 Only locally-changed options are stored in user-config now. Log levels revised.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 17
diff changeset
133
32eff0e01c05 Only locally-changed options are stored in user-config now. Log levels revised.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 17
diff changeset
134 Thrown exceptions should use an exception class specific to at least the package involved to enable specific catching of errors. Exception classes should be defined within a module exception.d in the package directory. Exception classes should generally follow the conventions within mde/exception.d to aid in providing reasonable error messages.
15
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
135
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
136
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
137
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
138 --- Translating strings ---
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
139 User output (internationalization support): i18n.I18nTranslation is designed to fetch a full string and optionally an associated descripion given an identifier. The identifier may also be a code symbol, and should be brief, in English, and give at least some idea of its meaning, since if no translation is available the identifier will be output. For example: "example message" or "exampleMessage", not "An example of a message". For any new entry created, at least one full entry should be added to the i18n database for some form of English so that:
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
140 (a) there is something available to translate to other locales
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
141 (b) English developers can understand what it means