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, but use assert for
15 A program should be light and agile, its subroutines
16 connected like a string of pearls. The spirit and intent of
17 the program should be retained throughout. There should be
18 neither too little nor too much, neither needless loops nor
19 useless variables, neither lack of structure nor overwhelming
22 A program should follow the 'Law of Least
23 Astonishment'. What is this law? It is simply that the
24 program should always respond to the user in the way that
27 A program, no matter how complex, should act as a
28 single unit. The program should be directed by the logic
29 within rather than by outward appearances.
31 If the program fails in these requirements, it will be
32 in a state of disorder and confusion. The only way to correct
33 this is to rewrite the program.
35 -- Geoffrey James, "The Tao of Programming"
41 C++, /bin/sh and Python are preferred. Perl is not.
42 Python code should use an indent of 8, using TAB characters.
46 Definitions of classes that are only accessed via pointers
47 (*) or references (&) shall not be included as include files.
53 ".cc" Implementation files
54 ".icc" Inline definition files
55 ".tcc" non inline Template defs
62 (append '(("\\.make$" . makefile-mode)
64 ("\\.icc$" . c++-mode)
65 ("\\.tcc$" . c++-mode)
67 ("\\.pod$" . text-mode)
73 The class Class_name_abbreviation is coded in file(class-name-abbr.*)
81 (add-hook 'c++-mode-hook
82 '(lambda() (c-set-style "gnu")
87 If you like using font-lock, you can also add this to your file(.emacs):
90 (setq font-lock-maximum-decoration t)
91 (setq c++-font-lock-keywords-3
93 c++-font-lock-keywords-3
94 '(("\\b\\([a-zA-Z_]+_\\)\\b" 1 font-lock-variable-name-face)
95 ("\\b\\([A-Z]+[a-z_]+\\)\\b" 1 font-lock-type-face))
99 nsubsect(CLASSES and TYPES:)
103 AClass_name (for Abbreviation_class_name)
110 Type Class::member_type_
111 Type Class::member_type()
114 the code(type) is a Hungarian notation postfix for code(Type). See below
118 Macros should be written completely in uppercase
120 The code should not be compilable if proper macro declarations are not
123 Don't laugh. It took us a whole evening/night to figure out one of
124 these bugs, because we had a macro that looked like
125 code(DECLARE_VIRTUAL_FUNCTIONS()).
127 nsubsect(BROKEN CODE)
129 Broken code (hardwired dependencies, hardwired constants, slow
130 algorithms and obvious limitations) should be marked as such: either
131 with a verbose TODO, or with a short "ugh" comment.
135 The source is commented in the DOC++ style. Check out doc++ at
136 lurl(http://www.zib.de/Visual/software/doc++/index.html)
140 C style comments for multiline comments.
141 They come before the thing to document.
148 Long class documentation.
151 TODO Fix boring_member()
163 short memo. long doco of member()
164 @param description of arguments
167 Rettype member(Argtype);
171 data_member_ = 121; // ugh
177 Unfortunately most of the code isn't really documented that good.
180 nsubsect(MEMBERS (2))
185 ///check that *this satisfies its invariants, abort if not.
188 /// print *this (and substructures) to debugging log
192 protected member. Usually invoked by non-virtual XXXX()
196 /**add some data to *this.
197 Presence of these methods usually imply that it is not feasible to this
202 /// replace some data of *this
206 nsubsect(Constructor)
208 Every class should have a default constructor.
210 Don't use non-default constructors if this can be avoided:
216 is less readable than
226 Foo f(Foo_convert::int_to_foo (1))
229 nsect(HUNGARIAN NOTATION NAMING CONVENTION)
231 Proposed is a naming convention derived from the so-called
232 em(Hungarian Notation).
236 The Hungarian Notation was conceived by or at least got its name from,
237 the hungarian programmer Charles Simonyi. It is a naming convention
238 with the aim to make code more readable (for fellow programmers), and
239 more accessible for programmers that are new to a project.
241 The essence of the Hungarian Notation is that every identifier has a
242 part which identifies its type (for functions this is the result
243 type). This is particularly useful in object oriented programming,
244 where a particular object implies a specific interface (a set of
245 member functions, perhaps some redefined operators), and for
246 accounting heap allocated memory pointers and links.
250 Another fun quote from Microsoft Secrets:
253 The Hungarian naming convention gives developers the ability
254 to read other people's code relatively easily, with a minmum
255 number of comments in the source code. Jon De Vann estimated
256 that only about 1 percent of all lines in the Excel product
257 code consist of comments, but the code is still very
258 understandable due to the use of Hungarian: "if you look at
259 our source code, you also notice very few comments. Hungarian
260 gives us the ability to go in and read code..."
263 Wow! If you use Hungarian you don't have to document your software!
264 Just think of the hours I have wasted documenting while this "silver bullet"
265 existed. I feel so stupid and ashamed! (Didn't MMM-Brooks say `There is
266 no silver bullet?' --HWN)
269 nsubsect(Disadvantages)
272 it()more keystrokes (disk space!)
273 it()it looks silly code(get_slu_p())
274 it()it looks like code from micro suckers
275 it()(which) might scare away some (otherwise good?)
276 progammers, or make you a paria in the free
278 it()it has ambiguities
279 it()not very useful if not used consistently
280 it()usefullness in em(very large) (but how many classes is very large?)
287 it()learn about cut and paste / use emacs or vi
288 or lean to type using ten fingers
289 it()Use emacs dabbrev-expand, with dabbrev-case-fold-search set to nil.
290 it()use no, or pick less silly, abbrvs.
291 it()use non-ambiguous postfixes code(identifier_name_type_modifier[_modifier])
292 it()There is no need for Hungarian if the scope of the variable is small,
293 ie. local variables, arguments in function definitions (not
297 Macros, code(enum)s and code(const)s are all uppercase,
298 with the parts of the names separated by underscores.
304 unsigned char. (The postfix _by is ambiguous)
318 Zero terminated c string
323 nsubsect(User defined types)
330 Slur* slur_p = new Slur;
335 The following types modify the meaning of the prefix.
336 These are preceded by the prefixes:
344 const. Note that the proper order is code(Type const)
345 i.s.o. code(const Type)
347 A const pointer. This would be equivalent to code(_c_l), but since any
348 "const" pointer has to be a link (you can't delete a const pointer),
351 temporary pointer to object (link)
353 pointer to newed object
360 Adjectives such as global and static should be spelled out in full.
361 They come before the noun that they refer to, just as in normal english.
364 foo_global_i: a global variable of type int commonly called "foo".
367 static class members do not need the static_ prefix in the name (the
368 Class::var notation usually makes it clear that it is static)
372 Variable loop: an integer
374 Temporary variable: an unsigned integer
376 Variable test: a character
377 dit(code(first_name_str))
378 Variable first_name: a String class object
379 dit(code(last_name_ch_a))
380 Variable last_name: a code(char) array
382 Variable foo: an code(Int*) that you must delete
384 Variable bar: an code(Int*) that you must not delete
387 Generally default arguments are taboo, except for nil pointers.
389 The naming convention can be quite conveniently memorised, by
390 expressing the type in english, and abbreviating it
393 static Array<int*> foo
396 code(foo) can be described as "the static int-pointer user-array", so you get
406 For some tasks, some scripts are supplied, notably creating patches, a
407 mirror of the website, generating the header to put over cc and hh
408 files, doing a release.
412 The following generic identifications are used:
421 Intervals are pictured lying on a horizontal numberline (Interval[-1]
422 is the minimum). The 2D plane has +x on the right, +y pointing up.