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)))
21 (add-hook 'c++-mode-hook
22 '(lambda() (c-set-style "Stroustrup")
27 =head2 CLASSES and TYPES:
30 AClass_name (for Abbreviation_class_name)
35 Type Class::member_type_
37 the C<type> is a Hungarian notation postfix for $C<Type>$. See below
42 The source is commented in the DOC++ style. Check out doc++ at
43 http://www.zib.de/Visual/software/doc++/index.html
47 Long class documentation.
51 /** short description.
59 short memo. long doco of member()
67 Unfortunately most of the code isn't really documented that good.
72 A lot of classes in LilyPond start with 'P', this is to distinguish
73 certain parts of LilyPond: the P stands for Printer, and the P-classes
74 are supposed to be more lowlevel than the others. Example:
76 Staff uses PStaff, PScore and PCol to do the typesetting of
77 symbols. Staff is the "brains" for PStaff
79 NB: in PCursor (which is part of the library) P stands for PointerCursor
86 ///check that *this satisfies its invariants, abort if not.
89 /// print *this (and substructures) to debugging log
93 protected member. Usually invoked by non-virtual XXXX()
97 /**add some data to *this.
98 Presence of these methods usually imply that it is not feasible to this
103 /// replace some data of *this
106 =head1 HUNGARIAN NOTATION NAMING CONVENTION
108 Proposed is a naming convention derived from the so-called I<Hungarian
113 The Hungarian Notation was conceived by or at least got its name from,
114 the hungarian programmer x. It is a naming convention with the aim to
115 make code more readable (for fellow programmers) and more accessible
116 for programmers that are new to a project.
118 The essence of the Hungarian Notation is that every identifier has a
119 part which identifies its type (for functions this is the result
120 type). This is particularly useful in object oriented programming,
121 where a particular object implies a specific interface (a set of
122 member functions, perhaps some redefined operators), and for
123 accounting heap allocated memory pointers and links.
127 Another fun quote from Microsoft Secrets:
130 The Hungarian naming convention gives developers the ability
131 to read other people's code relatively easily, with a minmum
132 number of comments in the source code. Jon De Vann estimated
133 that only about 1 percent of all lines in the Excel product
134 code consist of comments, but the code is still very
135 understandable due to the use of Hungarian: "if you look at
136 our source code, you also notice very few comments. Hungarian
137 gives us the ability to go in and read code..."
140 Wow! If you use Hungarian you don't have to document your software!
141 Just think of the hours I have wasted documenting while this "silver bullet"
142 existed. I feel so stupid and ashamed!
149 more keystrokes (disk space!)
152 it looks silly C<get_slu_p()>
155 it looks like code from micro suckers
158 (which) might scare away some (otherwise good?)
159 progammers, or make you a paria in the free
166 not very useful if not used consistently
169 usefullness in I<very large>
170 (but how many classes is very large?)
182 learn about cut and paste / use emacs or vi
183 or lean to type using ten fingers
186 Use emacs dabbrev-expand, with dabbrev-case-fold-search set to nil.
189 use no, or pick less silly, abbrvs.
192 use non-ambiguous postfixes C<identifier_name_type_modifier[_modifier]>
195 Macros, C<enum>s and C<const>s are all uppercase,
196 with the parts of the names separated by underscores.
203 unsigned cher. (The postfix _by is ambiguous)
224 Zero terminated c string
231 =head2 User defined types
238 Slur* slur_p = new Slur;
242 The following types modify the meaning of the prefix.
243 These are precede the prefixes:
257 temporary pointer to object (link)
260 pointer to newed object
270 Variable loop: an integer
273 Temporary variable: an unsigned integer
276 Variable Test: a character
278 =item C<first_name_str>
279 Variable first_name: a String class object
281 =item C<first_name_ch_a>
282 Variable first_name: a C<char> array
285 Variable Loop: an C<Int*> that you must delete
288 Variable Loop: an C<Int*> that you must not delete