3 CodingStyle - standards while programming for LilyPond
7 Please use these standards while doing programming for LilyPond
9 Functions and methods do not return errorcodes, but use assert for
17 (add-hook 'c-mode-hook
18 '(lambda ()(setq c-basic-offset 4)))
19 (add-hook 'c++-mode-hook
20 '(lambda() (c-set-style "Stroustrup")
25 The class C<This_is_a_class> is declared in F<this-is-a-class.hh> and
26 implemented in F<this-is-a-class.cc>.
28 =head2 CLASSES and TYPES:
31 AClass_name (for Abbreviation_class_name)
36 Type Class::member_type_
38 the C<type> is a Hungarian notation postfix for C<Type>. See below
43 The source is commented in the DOC++ style. Check out doc++ at
44 http://www.zib.de/Visual/software/doc++/index.html
47 C style comments for multiline comments.
54 Long class documentation.
67 short memo. long doco of member()
68 @param description of arguments
71 Rettype member(Argtype);
77 Unfortunately most of the code isn't really documented that good.
82 A lot of classes in LilyPond start with 'P', this is to distinguish
83 certain parts of LilyPond: the P stands for Printer, and the P-classes
84 are supposed to be more lowlevel than the others. Example:
86 Staff uses PStaff, PScore and PCol to do the typesetting of
87 symbols. Staff is the "brains" for PStaff
89 NB: in PCursor (which is part of the library) P stands for PointerCursor
96 ///check that *this satisfies its invariants, abort if not.
99 /// print *this (and substructures) to debugging log
103 protected member. Usually invoked by non-virtual XXXX()
107 /**add some data to *this.
108 Presence of these methods usually imply that it is not feasible to this
113 /// replace some data of *this
116 =head1 HUNGARIAN NOTATION NAMING CONVENTION
118 Proposed is a naming convention derived from the so-called I<Hungarian
123 The Hungarian Notation was conceived by or at least got its name from,
124 the hungarian programmer x. It is a naming convention with the aim to
125 make code more readable (for fellow programmers) and more accessible
126 for programmers that are new to a project.
128 The essence of the Hungarian Notation is that every identifier has a
129 part which identifies its type (for functions this is the result
130 type). This is particularly useful in object oriented programming,
131 where a particular object implies a specific interface (a set of
132 member functions, perhaps some redefined operators), and for
133 accounting heap allocated memory pointers and links.
137 Another fun quote from Microsoft Secrets:
140 The Hungarian naming convention gives developers the ability
141 to read other people's code relatively easily, with a minmum
142 number of comments in the source code. Jon De Vann estimated
143 that only about 1 percent of all lines in the Excel product
144 code consist of comments, but the code is still very
145 understandable due to the use of Hungarian: "if you look at
146 our source code, you also notice very few comments. Hungarian
147 gives us the ability to go in and read code..."
150 Wow! If you use Hungarian you don't have to document your software!
151 Just think of the hours I have wasted documenting while this "silver bullet"
152 existed. I feel so stupid and ashamed!
159 more keystrokes (disk space!)
162 it looks silly C<get_slu_p()>
165 it looks like code from micro suckers
168 (which) might scare away some (otherwise good?)
169 progammers, or make you a paria in the free
176 not very useful if not used consistently
179 usefullness in I<very large>
180 (but how many classes is very large?)
192 learn about cut and paste / use emacs or vi
193 or lean to type using ten fingers
196 Use emacs dabbrev-expand, with dabbrev-case-fold-search set to nil.
199 use no, or pick less silly, abbrvs.
202 use non-ambiguous postfixes C<identifier_name_type_modifier[_modifier]>
205 Macros, C<enum>s and C<const>s are all uppercase,
206 with the parts of the names separated by underscores.
213 unsigned cher. (The postfix _by is ambiguous)
234 Zero terminated c string
241 =head2 User defined types
248 Slur* slur_p = new Slur;
252 The following types modify the meaning of the prefix.
253 These are precede the prefixes:
267 temporary pointer to object (link)
270 pointer to newed object
280 Variable loop: an integer
283 Temporary variable: an unsigned integer
286 Variable Test: a character
288 =item C<first_name_str>
289 Variable first_name: a String class object
291 =item C<first_name_ch_a>
292 Variable first_name: a C<char> array
295 Variable Loop: an C<Int*> that you must delete
298 Variable Loop: an C<Int*> that you must not delete