Documentation/CodingStyle.pod

   1 =head1 NAME
   2
   3 CodingStyle - standards while programming for LilyPond
   4
   5 =head1 DESCRIPTION
   6
   7 Please use these standards while doing programming for LilyPond
   8
   9 Functions and methods do not return errorcodes, but use assert for
  10 checking status.
  11
  12 =head2 Quote:
  13
  14 A program should be light and agile, its subroutines
  15 connected like a strings 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
  19 rigidity.
  20
  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
  24 astonishes him least.
  25
  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.
  29
  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.
  33
  34 -- Geoffrey James, "The Tao of Programming"
  35
  36 =head2 INDENTATION
  37
  38 in emacs:
  39
  40
  41         (add-hook 'c-mode-hook
  42                   '(lambda ()(setq c-basic-offset 4)))
  43
  44
  45         (add-hook 'c++-mode-hook
  46                   '(lambda() (c-set-style "Stroustrup")
  47                      )
  48                   )
  49
  50
  51 =head2 CLASSES and TYPES:
  52
  53         This_is_a_class
  54         AClass_name     (for Abbreviation_class_name)
  55
  56 =head2 DATA MEMBERS
  57
  58         Class::member()
  59         Type Class::member_type_
  60
  61 the C<type> is a Hungarian notation postfix for $C<Type>$. See below
  62
  63
  64 =head2 COMMENTS
  65
  66 The source is commented in the DOC++ style.  Check out doc++ at
  67 http://www.zib.de/Visual/software/doc++/index.html
  68
  69         /*
  70                 C style comments for multiline comments.
  71                 [...]
  72         */
  73
  74
  75         /**
  76                 short description.
  77                 Long class documentation.
  78                 (Hungarian postfix)
  79         */
  80         class Class {
  81                 /**
  82                   short description.
  83                   long description
  84                 */
  85
  86                 Data data_member_;
  87
  88
  89                 /**
  90                         short memo. long doco of member()
  91                         @param description of arguments
  92                         @return Rettype
  93                 */
  94                 Rettype member(Argtype);
  95
  96                 /// memo only
  97                 boring_member();
  98         };
  99
 100 Unfortunately most of the code isn't really documented that good.
 101
 102
 103 =head2 CLASSNAMES (2)
 104
 105 A lot of classes in LilyPond start with 'P', this is to distinguish
 106 certain parts of LilyPond: the P stands for Printer, and the P-classes
 107 are supposed to be more lowlevel than the others. Example:
 108
 109 Staff uses PStaff, PScore and PCol to do the typesetting of
 110 symbols. Staff is  the "brains" for PStaff
 111
 112 NB: in PCursor (which is part of the library) P stands for PointerCursor
 113
 114
 115 =head2 MEMBERS (2)
 116
 117 Standard methods:
 118
 119         ///check that *this satisfies its invariants, abort if not.
 120         void OK() const
 121
 122         /// print *this (and substructures) to debugging log
 123         void print() const
 124
 125         /**
 126         protected member. Usually invoked by non-virtual XXXX()
 127         */
 128         virtual do_XXXX()
 129
 130         /**add some data to *this.
 131         Presence of these methods usually imply that it is not feasible to this
 132         via  a constructor
 133         */
 134         add( .. )
 135
 136         /// replace some data of *this
 137         set( .. )
 138
 139 =head1 HUNGARIAN NOTATION NAMING CONVENTION
 140
 141 Proposed is a naming convention derived from the so-called I<Hungarian
 142 Notation>.
 143
 144 =head2 Hungarian
 145
 146 The Hungarian Notation was conceived by or at least got its name from,
 147 the hungarian programmer Charles Simonyi.  It is a naming convention
 148 with the aim to make code more readable (for fellow programmers), and
 149 more accessible for programmers that are new to a project.
 150
 151 The essence of the Hungarian Notation is that every identifier has a
 152 part which identifies its type (for functions this is the result
 153 type).  This is particularly useful in object oriented programming,
 154 where a particular object implies a specific interface (a set of
 155 member functions, perhaps some redefined operators), and for
 156 accounting heap allocated memory pointers and links.
 157
 158 =head2 Advantages
 159
 160 Another fun quote from Microsoft Secrets:
 161
 162
 163         The Hungarian naming convention gives developers the ability
 164         to read other people's code relatively easily, with a minmum
 165         number of comments in the source code.  Jon De Vann estimated
 166         that only about 1 percent of all lines in the Excel product
 167         code consist of comments, but the code is still very
 168         understandable due to the use of Hungarian: "if you look at
 169         our source code, you also notice very few comments.  Hungarian
 170         gives us the ability to go in and read code..."
 171
 172
 173 Wow! If you use Hungarian you don't have to document your software!
 174 Just think of the hours I have wasted documenting while this "silver bullet"
 175 existed. I feel so stupid and ashamed!
 176
 177 =head2 Disadvantages
 178
 179 =over 5
 180
 181 =item *
 182
 183 more keystrokes (disk space!)
 184
 185 =item *
 186
 187 it looks silly C<get_slu_p()>
 188
 189 =item *
 190
 191 it looks like code from micro suckers
 192
 193 =item *
 194
 195 (which) might scare away some (otherwise good?)
 196 progammers, or make you a paria in the free
 197 software community
 198
 199 =item *
 200
 201 it has ambiguities
 202
 203 =item *
 204
 205 not very useful if not used consistently
 206
 207 =item *
 208
 209 usefullness in I<very large>
 210 (but how many classes is very large?)
 211 remains an issue.
 212
 213 =back
 214
 215
 216
 217 =head2 Proposal
 218
 219 =over 5
 220
 221 =item *
 222
 223 learn about cut and paste / use emacs or vi
 224 or lean to type using ten fingers
 225
 226 =item *
 227
 228 Use emacs dabbrev-expand, with dabbrev-case-fold-search set to nil.
 229
 230 =item *
 231
 232 use no, or pick less silly, abbrvs.
 233
 234 =item *
 235
 236 use non-ambiguous postfixes C<identifier_name_type_modifier[_modifier]>
 237 =back
 238
 239 Macros, C<enum>s and C<const>s are all uppercase,
 240 with the parts of the names separated by underscores.
 241
 242 =head2 Types
 243
 244 =over 5
 245
 246 =item C<byte>
 247
 248
 249 unsigned char. (The postfix _by is ambiguous)
 250
 251 =item C<b>
 252
 253
 254 bool
 255
 256 =item C<bi>
 257
 258 bit
 259
 260 =item C<ch>
 261
 262 char
 263
 264 =item C<f>
 265
 266 float
 267
 268 =item C<i>
 269
 270 signed integer
 271
 272 =item C<str>
 273
 274 string class
 275
 276 =item C<sz>
 277
 278 Zero terminated c string
 279
 280 =item C<u>
 281
 282 unsigned integer
 283
 284 =back
 285
 286 =head2 User defined types
 287
 288
 289         /** Slur blah. blah.
 290         (slur)
 291         */
 292         class Slur {};
 293         Slur* slur_p = new Slur;
 294
 295 =head2 Modifiers
 296
 297 The following types modify the meaning of the prefix.
 298 These are precede the prefixes:
 299
 300 =over 5
 301
 302 =item C<a>
 303
 304 array
 305
 306 =item C<array>
 307
 308 user built array.
 309
 310 =item C<c>
 311
 312 const. Note that the proper order C<Type const> i.s.o. C<const Type>
 313
 314 =item C<l>
 315
 316 temporary pointer to object (link)
 317
 318 =item C<p>
 319
 320 pointer to newed object
 321
 322 =item C<r>
 323
 324 reference
 325
 326 =back
 327
 328 =over 5
 329
 330 =item C<loop_i>
 331
 332 Variable loop: an integer
 333
 334 =item C<u>
 335
 336 Temporary variable: an unsigned integer
 337
 338 =item C<test_ch>
 339
 340 Variable test: a character
 341
 342 =item C<first_name_str>
 343
 344 Variable first_name: a String class object
 345
 346 =item C<last_name_ch_a>
 347
 348 Variable last_name: a C<char> array
 349
 350 =item C<foo_i_p>
 351
 352 Variable foo: an C<Int*> that you must delete
 353
 354 =item C<bar_i_l>
 355
 356 Variable bar: an C<Int*> that you must not delete
 357
 358 =back
 359
 360
 361