Mercurial > projects > mde

comparison codeDoc/policies.txt @ 32:316b0230a849

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Lots more work on the GUI. Also renamed lots of files. Lots of changes to the GUI. Renderer is now used exclusively for rendering and WidgetDecoration is gone. Renamed lots of files to conform to case policies. committer: Diggory Hardy <diggory.hardy@gmail.com>
author Diggory Hardy <diggory.hardy@gmail.com>
date Wed, 30 Apr 2008 18:05:56 +0100
parents 611f7b9063c6
children 57d000574d75
comparison
equal deleted inserted replaced
31:baa87e68d7dc 32:316b0230a849
51 51
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. 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.
53 53
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. 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.
55 55
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. 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. Don't capitalise acronyms like SDL; instead use capitalisation like outlined above (personally I hate doing so but it does make things clearer).
57 57
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. 58 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.
59 59
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). 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).
61 61
62 62
63 63
75 75
76 76
77 --- Package design principle --- 77 --- Package design principle ---
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. 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.
79 79
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.
81 80
82 Chain dependancies: If at all possible, avoid chain dependancies (e.g. use interfaces). Chain dependancies can cause many problems. 81 Module imports:
82 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.
83
84 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.
85
86 Where it is not obvious, show what the import is used for with a comment or selective import showing which symbols are used.
87
88 Chain dependancies: Avoid chain dependancies between modules (e.g. use interfaces). Chain dependancies can cause many problems.
83 89
84 90
85 91
86 --- Initialisation / cleanup --- 92 --- Initialisation / cleanup ---
87 This can be done in two ways: 93 This can be done in two ways: