1 \input texinfo @c -*-texinfo-*-
2 @setfilename CodingStyle.info
3 @settitle CodingStyle - standards while programming for GNU
12 @chapter CodingStyle - standards while programming for GNU
17 @unnumberedsec DESCRIPTION
20 We use these standards while doing programming for GNU LilyPond. If
21 you do some hacking, we appreciate it if you would follow this rules,
22 but if you don't, we still like you.
24 Functions and methods do not return errorcodes.
28 A program should be light and agile, its subroutines
29 connected like a string of pearls. The spirit and intent of
30 the program should be retained throughout. There should be
31 neither too little nor too much, neither needless loops nor
32 useless variables, neither lack of structure nor overwhelming
35 A program should follow the 'Law of Least
36 Astonishment'. What is this law? It is simply that the
37 program should always respond to the user in the way that
40 A program, no matter how complex, should act as a
41 single unit. The program should be directed by the logic
42 within rather than by outward appearances.
44 If the program fails in these requirements, it will be
45 in a state of disorder and confusion. The only way to correct
46 this is to rewrite the program.
48 -- Geoffrey James, "The Tao of Programming"
52 @unnumberedsubsec LANGUAGES
54 C++, /bin/sh and Python are preferred. Perl is not.
55 Python code should use an indent of 8, using TAB characters.
57 @unnumberedsubsec FILES
59 Definitions of classes that are only accessed via pointers
60 (*) or references (&) shall not be included as include files.
67 ".cc" Implementation files
68 ".icc" Inline definition files
69 ".tcc" non inline Template defs
78 (append '(("\\.make$" . makefile-mode)
80 ("\\.icc$" . c++-mode)
81 ("\\.tcc$" . c++-mode)
83 ("\\.pod$" . text-mode)
90 The class Class_name_abbreviation is coded in @file{class-name-abbr.*}
92 @unnumberedsubsec INDENTATION
98 (add-hook 'c++-mode-hook
99 '(lambda() (c-set-style "gnu")
105 If you like using font-lock, you can also add this to your @file{.emacs}:
109 (setq font-lock-maximum-decoration t)
110 (setq c++-font-lock-keywords-3
112 c++-font-lock-keywords-3
113 '(("\\b\\([a-zA-Z_]+_\\)\\b" 1 font-lock-variable-name-face)
114 ("\\b\\([A-Z]+[a-z_]+\\)\\b" 1 font-lock-type-face))
119 @unnumberedsubsec CLASSES and TYPES:
127 @unnumberedsubsec MEMBERS
132 Type Class::member_type_
133 Type Class::member_type ()
137 the @code{type} is a Hungarian notation postfix for @code{Type}. See below
139 @unnumberedsubsec MACROS
141 Macros should be written completely in uppercase
143 The code should not be compilable if proper macro declarations are not
146 Don't laugh. It took us a whole evening/night to figure out one of
147 these bugs, because we had a macro that looked like
148 @code{DECLARE_VIRTUAL_FUNCTIONS ()}.
150 @unnumberedsubsec BROKEN CODE
152 Broken code (hardwired dependencies, hardwired constants, slow
153 algorithms and obvious limitations) should be marked as such: either
154 with a verbose TODO, or with a short "ugh" comment.
156 @unnumberedsubsec COMMENTS
158 The source is commented in the DOC++ style. Check out doc++ at
159 @uref{http://www.zib.de/Visual/software/doc++/index.html}
164 C style comments for multiline comments.
165 They come before the thing to document.
171 Long class documentation.
174 TODO Fix boring_member ()
185 short memo. long doco of member ()
186 @@param description of arguments
189 Rettype member (Argtype);
193 data_member_ = 121; // ugh
200 Unfortunately most of the code isn't really documented that good.
202 @unnumberedsubsec MEMBERS (2)
208 ///check that *this satisfies its invariants, abort if not.
211 /// print *this (and substructures) to debugging log
215 protected member. Usually invoked by non-virtual XXXX ()
219 /**add some data to *this.
220 Presence of these methods usually imply that it is not feasible to this
225 /// replace some data of *this
230 @unnumberedsubsec Constructor
232 Every class should have a default constructor.
234 Don't use non-default constructors if this can be avoided:
242 is less readable than
255 Foo f(Foo_convert::int_to_foo (1))
259 @unnumberedsec HUNGARIAN NOTATION NAMING CONVENTION
262 Proposed is a naming convention derived from the so-called
263 @emph{Hungarian Notation}. Macros, @code{enum}s and @code{const}s are all
264 uppercase, with the parts of the names separated by underscores.
266 @unnumberedsubsec Types
270 unsigned char. (The postfix _by is ambiguous)
284 Zero terminated c string
289 @unnumberedsubsec User defined types
297 Slur* slur_p = new Slur;
301 @unnumberedsubsec Modifiers
303 The following types modify the meaning of the prefix.
304 These are preceded by the prefixes:
312 const. Note that the proper order is @code{Type const}
313 i.s.o. @code{const Type}
315 A const pointer. This would be equivalent to @code{_c_l}, but since any
316 "const" pointer has to be a link (you can't delete a const pointer),
319 temporary pointer to object (link)
321 pointer to newed object
326 @unnumberedsubsec Adjective
328 Adjectives such as global and static should be spelled out in full.
329 They come before the noun that they refer to, just as in normal english.
333 foo_global_i: a global variable of type int commonly called "foo".
337 static class members do not need the static_ prefix in the name (the
338 Class::var notation usually makes it clear that it is static)
342 Variable loop: an integer
344 Temporary variable: an unsigned integer
346 Variable test: a character
347 @item @code{first_name_str}
348 Variable first_name: a String class object
349 @item @code{last_name_ch_a}
350 Variable last_name: a @code{char} array
352 Variable foo: an @code{Int*} that you must delete
354 Variable bar: an @code{Int*} that you must not delete
357 Generally default arguments are taboo, except for nil pointers.
359 The naming convention can be quite conveniently memorised, by
360 expressing the type in english, and abbreviating it
364 static Array<int*> foo
368 @code{foo} can be described as "the static int-pointer user-array", so you get
377 @unnumberedsec MISCELLANEOUS
380 For some tasks, some scripts are supplied, notably creating patches, a
381 mirror of the website, generating the header to put over cc and hh
382 files, doing a release.
386 The following generic identifications are used:
397 Intervals are pictured lying on a horizontal numberline (Interval[-1]
398 is the minimum). The 2D plane has +x on the right, +y pointing up.