1 report(CodingStyle - standards while programming for GNU
2 LilyPond)(Han-Wen Nienhuys and Jan Nieuwenhuizen)()()
6 We use these standards while doing programming for GNU LilyPond. If
7 you do some hacking, we appreciate it if you would follow this rules,
8 but if you don't, we still like you.
10 Functions and methods do not return errorcodes.
14 A program should be light and agile, its subroutines
15 connected like a string of pearls. The spirit and intent of
16 the program should be retained throughout. There should be
17 neither too little nor too much, neither needless loops nor
18 useless variables, neither lack of structure nor overwhelming
21 A program should follow the 'Law of Least
22 Astonishment'. What is this law? It is simply that the
23 program should always respond to the user in the way that
26 A program, no matter how complex, should act as a
27 single unit. The program should be directed by the logic
28 within rather than by outward appearances.
30 If the program fails in these requirements, it will be
31 in a state of disorder and confusion. The only way to correct
32 this is to rewrite the program.
34 -- Geoffrey James, "The Tao of Programming"
40 C++, /bin/sh and Python are preferred. Perl is not.
41 Python code should use an indent of 8, using TAB characters.
45 Definitions of classes that are only accessed via pointers
46 (*) or references (&) shall not be included as include files.
52 ".cc" Implementation files
53 ".icc" Inline definition files
54 ".tcc" non inline Template defs
61 (append '(("\\.make$" . makefile-mode)
63 ("\\.icc$" . c++-mode)
64 ("\\.tcc$" . c++-mode)
66 ("\\.pod$" . text-mode)
72 The class Class_name_abbreviation is coded in file(class-name-abbr.*)
80 (add-hook 'c++-mode-hook
81 '(lambda() (c-set-style "gnu")
86 If you like using font-lock, you can also add this to your file(.emacs):
89 (setq font-lock-maximum-decoration t)
90 (setq c++-font-lock-keywords-3
92 c++-font-lock-keywords-3
93 '(("\\b\\([a-zA-Z_]+_\\)\\b" 1 font-lock-variable-name-face)
94 ("\\b\\([A-Z]+[a-z_]+\\)\\b" 1 font-lock-type-face))
98 nsubsect(CLASSES and TYPES:)
108 Type Class::member_type_
109 Type Class::member_type ()
112 the code(type) is a Hungarian notation postfix for code(Type). See below
116 Macros should be written completely in uppercase
118 The code should not be compilable if proper macro declarations are not
121 Don't laugh. It took us a whole evening/night to figure out one of
122 these bugs, because we had a macro that looked like
123 code(DECLARE_VIRTUAL_FUNCTIONS ()).
125 nsubsect(BROKEN CODE)
127 Broken code (hardwired dependencies, hardwired constants, slow
128 algorithms and obvious limitations) should be marked as such: either
129 with a verbose TODO, or with a short "ugh" comment.
133 The source is commented in the DOC++ style. Check out doc++ at
134 lurl(http://www.zib.de/Visual/software/doc++/index.html)
138 C style comments for multiline comments.
139 They come before the thing to document.
146 Long class documentation.
149 TODO Fix boring_member ()
161 short memo. long doco of member ()
162 @param description of arguments
165 Rettype member (Argtype);
169 data_member_ = 121; // ugh
175 Unfortunately most of the code isn't really documented that good.
178 nsubsect(MEMBERS (2))
183 ///check that *this satisfies its invariants, abort if not.
186 /// print *this (and substructures) to debugging log
190 protected member. Usually invoked by non-virtual XXXX ()
194 /**add some data to *this.
195 Presence of these methods usually imply that it is not feasible to this
200 /// replace some data of *this
204 nsubsect(Constructor)
206 Every class should have a default constructor.
208 Don't use non-default constructors if this can be avoided:
214 is less readable than
224 Foo f(Foo_convert::int_to_foo (1))
227 nsect(HUNGARIAN NOTATION NAMING CONVENTION)
229 Proposed is a naming convention derived from the so-called
230 em(Hungarian Notation). Macros, code(enum)s and code(const)s are all
231 uppercase, with the parts of the names separated by underscores.
237 unsigned char. (The postfix _by is ambiguous)
251 Zero terminated c string
256 nsubsect(User defined types)
263 Slur* slur_p = new Slur;
268 The following types modify the meaning of the prefix.
269 These are preceded by the prefixes:
277 const. Note that the proper order is code(Type const)
278 i.s.o. code(const Type)
280 A const pointer. This would be equivalent to code(_c_l), but since any
281 "const" pointer has to be a link (you can't delete a const pointer),
284 temporary pointer to object (link)
286 pointer to newed object
293 Adjectives such as global and static should be spelled out in full.
294 They come before the noun that they refer to, just as in normal english.
297 foo_global_i: a global variable of type int commonly called "foo".
300 static class members do not need the static_ prefix in the name (the
301 Class::var notation usually makes it clear that it is static)
305 Variable loop: an integer
307 Temporary variable: an unsigned integer
309 Variable test: a character
310 dit(code(first_name_str))
311 Variable first_name: a String class object
312 dit(code(last_name_ch_a))
313 Variable last_name: a code(char) array
315 Variable foo: an code(Int*) that you must delete
317 Variable bar: an code(Int*) that you must not delete
320 Generally default arguments are taboo, except for nil pointers.
322 The naming convention can be quite conveniently memorised, by
323 expressing the type in english, and abbreviating it
326 static Array<int*> foo
329 code(foo) can be described as "the static int-pointer user-array", so you get
339 For some tasks, some scripts are supplied, notably creating patches, a
340 mirror of the website, generating the header to put over cc and hh
341 files, doing a release.
345 The following generic identifications are used:
354 Intervals are pictured lying on a horizontal numberline (Interval[-1]
355 is the minimum). The 2D plane has +x on the right, +y pointing up.