Mercurial > projects > mde

annotate codeDoc/policies.txt @ 163:24d77c52243f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Provided sensible conversions for setting the value of one AStringContent from another, along with unittest. Updated layout and Translation unittests to run.
author Diggory Hardy <diggory.hardy@gmail.com>
date Sat, 23 May 2009 15:47:32 +0200
parents 9cff74f68b84
children 3d58adc17d20
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
26
611f7b9063c6 Changed the licensing and removed a few dead files.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 24
diff changeset
5 This program is free software: you can redistribute it and/or modify it under the terms
611f7b9063c6 Changed the licensing and removed a few dead files.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 24
diff changeset
6 of the GNU General Public License as published by the Free Software Foundation, either
611f7b9063c6 Changed the licensing and removed a few dead files.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 24
diff changeset
7 version 2 of the License, or (at your option) any later version.
17
5f90774ea1ef Applied the GNU GPL v2 to mde.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 15
diff changeset
8
5f90774ea1ef Applied the GNU GPL v2 to mde.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 15
diff changeset
9 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
10 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
11 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
12
26
611f7b9063c6 Changed the licensing and removed a few dead files.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 24
diff changeset
13 You should have received a copy of the GNU General Public License
611f7b9063c6 Changed the licensing and removed a few dead files.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 24
diff changeset
14 along with this program. If not, see <http://www.gnu.org/licenses/>.
17
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
131
9cff74f68b84 Major revisions to popup handling. Buttons can close menus now, plus some smaller impovements. Removed Widget module.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 36
diff changeset
21 These are principles, not cast-iron rules, which I (Diggory aka Cyborg16) generally try to adhere to. If any other programmers have better principles to apply over these rules, they can use them.
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
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
36
57d000574d75 Enabled drawing on demand, and made the polling interval configurable.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 32
diff changeset
47 9 Floating point types
57d000574d75 Enabled drawing on demand, and made the polling interval configurable.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 32
diff changeset
48
57d000574d75 Enabled drawing on demand, and made the polling interval configurable.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 32
diff changeset
49
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
50
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 --- 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
53 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
54
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 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
56
131
9cff74f68b84 Major revisions to popup handling. Buttons can close menus now, plus some smaller impovements. Removed Widget module.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 36
diff changeset
57 Long lines: Aim to break long lines at around 80 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. It used to be 100 chars.
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
58
32
316b0230a849 Lots more work on the GUI. Also renamed lots of files.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 26
diff changeset
59 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. Don't capitalise acronyms like SDL; instead use capitalisation like outlined above (personally I hate doing so but it does make things clearer).
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
60
32
316b0230a849 Lots more work on the GUI. Also renamed lots of files.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 26
diff changeset
61 Module/file names: If the module corresponds directly to a class (possibly also with some associated classes), use the class name with correct Capitalisation as the module name. Otherwise, use lower case. Always use the correct case when importing a module to keep code portable.
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
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 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
64
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
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 --- 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
68 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
69
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 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
71
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 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
73
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 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
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 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
77
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
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 --- 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
81 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
82
32
316b0230a849 Lots more work on the GUI. Also renamed lots of files.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 26
diff changeset
83
316b0230a849 Lots more work on the GUI. Also renamed lots of files.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 26
diff changeset
84 Module imports:
316b0230a849 Lots more work on the GUI. Also renamed lots of files.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 26
diff changeset
85 Only publically import module A into module B if you can be fairly sure that any module C importing module B will also need module A.
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
86
32
316b0230a849 Lots more work on the GUI. Also renamed lots of files.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 26
diff changeset
87 Try to make it obvious which module the symbols you use come from. Sometimes using static or renamed imports is the best way to do this. Sometimes selective imports also help avoid confusion.
316b0230a849 Lots more work on the GUI. Also renamed lots of files.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 26
diff changeset
88
316b0230a849 Lots more work on the GUI. Also renamed lots of files.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 26
diff changeset
89 Where it is not obvious, show what the import is used for with a comment or selective import showing which symbols are used.
316b0230a849 Lots more work on the GUI. Also renamed lots of files.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 26
diff changeset
90
316b0230a849 Lots more work on the GUI. Also renamed lots of files.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 26
diff changeset
91 Chain dependancies: Avoid chain dependancies between modules (e.g. use interfaces). Chain dependancies can cause many problems.
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
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 --- 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
96 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
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 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
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 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
101
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
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 --- 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
105 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
106
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 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
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 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
110 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
111 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
112
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
113
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
114
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 --- 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
116 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
117
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 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
119 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
120 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
121 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
122 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
123 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
124
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
125 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
126 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
127 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
128 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
129 • 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
130 • warn messages may occur, and may indicate problems;
163
24d77c52243f Provided sensible conversions for setting the value of one AStringContent from another, along with unittest.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 131
diff changeset
131 • error messages indicate that something is definitely wrong (even for user input and 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
132 • 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
133
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
134 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
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 --- 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
139 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
140
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
141 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
142
32eff0e01c05 Only locally-changed options are stored in user-config now. Log levels revised.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 17
diff changeset
143 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
144
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
145
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
146
4608be19ebe2 Use OS paths (linux only for now), merging multiple paths. Init changes regarding options.
Diggory Hardy <diggory.hardy@gmail.com>
parents:
diff changeset
147 --- 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
148 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
149 (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
150 (b) English developers can understand what it means
36
57d000574d75 Enabled drawing on demand, and made the polling interval configurable.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 32
diff changeset
151
57d000574d75 Enabled drawing on demand, and made the polling interval configurable.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 32
diff changeset
152
57d000574d75 Enabled drawing on demand, and made the polling interval configurable.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 32
diff changeset
153
57d000574d75 Enabled drawing on demand, and made the polling interval configurable.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 32
diff changeset
154 --- Floating point types ---
57d000574d75 Enabled drawing on demand, and made the polling interval configurable.
Diggory Hardy <diggory.hardy@gmail.com>
parents: 32
diff changeset
155 The issue is whether to use float, double or real as the basic floating point type. In some cases which types are appropriate for use is set by the prototypes of external methods being used. In other cases, which type to use is left entirely to the user's discretion. Since even modern 32-bit CPUs support native 80-bit floating point operations, there seems little point in using floats. Since doubles are more widely supported than reals and provide sufficient precision for most purposes, double seems to be the ideal type to use. Actually some basic tests with 32-bit dmd on my athlon-64 (under 64-bit linux) show floats to be slower to use than doubles but faster than reals, so this appears to be a good choice for now.