Documentation/CodingStyle.pod

   1 =head1 NAME
   2
   3 CodingStyle - standards while programming for GNU LilyPond
   4
   5 =head1 DESCRIPTION
   6
   7 Please use these standards while doing programming for GNU 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 FILES
  37
  38 Definitions of classes that are only accessed via pointers
  39 (*) or references (&) shall not be included as include files.
  40
  41 Include files in C++ always have the file name extension ".hh".
  42
  43 Implementation files in C++ always have the file name
  44 extension ".cc".
  45
  46 Inline definition files always have the file name extension ".icc".
  47
  48 in emacs:
  49
  50         (setq auto-mode-alist
  51               (append '(("\\.make$" . makefile-mode)
  52                         ("\\.cc$" . c++-mode)
  53                         ("\\.icc$" . c++-mode)
  54                         ("\\.tcc$" . c++-mode)
  55                         ("\\.hh$" . c++-mode)
  56                         ("\\.pod$" . text-mode)
  57                         )
  58                       auto-mode-alist))
  59
  60
  61
  62 =head2 INDENTATION
  63
  64 in emacs:
  65
  66
  67         (add-hook 'c-mode-hook
  68                   '(lambda ()(setq c-basic-offset 4)))
  69
  70
  71         (add-hook 'c++-mode-hook
  72                   '(lambda() (c-set-style "Stroustrup")
  73                      )
  74                   )
  75
  76 If you like using font-lock, you can also add this to your F<.emacs>:
  77
  78         (setq font-lock-maximum-decoration t)
  79         (setq c++-font-lock-keywords-3
  80               (append
  81                c++-font-lock-keywords-3
  82                '(("\\b\\([a-zA-Z_]+_\\)\\b" 1 font-lock-variable-name-face)
  83                ("\\b\\([A-Z]+[a-z_]+\\)\\b" 1 font-lock-type-face))
  84                ))
  85
  86 =head2 CLASSES and TYPES:
  87
  88         This_is_a_class
  89         AClass_name     (for Abbreviation_class_name)
  90
  91 =head2 DATA MEMBERS
  92
  93         Class::member()
  94         Type Class::member_type_
  95
  96 the C<type> is a Hungarian notation postfix for C<Type>. See below
  97
  98
  99 =head2 BROKEN CODE
 100
 101 Broken code (hardwired dependencies, hardwired constants, slow
 102 algorithms and obvious limitations) should be marked as such:
 103 either with a verbose TODO, or with a short "ugh" comment.
 104
 105 =head2 COMMENTS
 106
 107 The source is commented in the DOC++ style.  Check out doc++ at
 108 http://www.zib.de/Visual/software/doc++/index.html
 109
 110         /*
 111                 C style comments for multiline comments.
 112                 They come before the thing to document.
 113                 [...]
 114         */
 115
 116
 117         /**
 118                 short description.
 119                 Long class documentation.
 120                 (Hungarian postfix)
 121
 122                 TODO Fix boring_member()
 123         */
 124         class Class {
 125                 /**
 126                   short description.
 127                   long description
 128                 */
 129
 130                 Data data_member_;
 131
 132
 133                 /**
 134                         short memo. long doco of member()
 135                         @param description of arguments
 136                         @return Rettype
 137                 */
 138                 Rettype member(Argtype);
 139
 140                 /// memo only
 141                 boring_member() {
 142                         data_member_ = 121; // ugh
 143                 }
 144         };
 145
 146
 147
 148 Unfortunately most of the code isn't really documented that good.
 149
 150
 151 =head2 CLASSNAMES (2)
 152
 153 A lot of classes in GNU LilyPond start with 'P', this is to distinguish
 154 certain parts of GNU LilyPond: the P stands for Printer, and the P-classes
 155 are supposed to be more lowlevel than the others. Example:
 156
 157 Staff uses PStaff, PScore and PCol to do the typesetting of
 158 symbols. Staff is  the "brains" for PStaff
 159
 160 NB: in PCursor (which is part of the library) P stands for PointerCursor
 161
 162
 163 =head2 MEMBERS (2)
 164
 165 Standard methods:
 166
 167         ///check that *this satisfies its invariants, abort if not.
 168         void OK() const
 169
 170         /// print *this (and substructures) to debugging log
 171         void print() const
 172
 173         /**
 174         protected member. Usually invoked by non-virtual XXXX()
 175         */
 176         virtual do_XXXX()
 177
 178         /**add some data to *this.
 179         Presence of these methods usually imply that it is not feasible to this
 180         via  a constructor
 181         */
 182         add( .. )
 183
 184         /// replace some data of *this
 185         set( .. )
 186
 187 =head1 HUNGARIAN NOTATION NAMING CONVENTION
 188
 189 Proposed is a naming convention derived from the so-called I<Hungarian
 190 Notation>.
 191
 192 =head2 Hungarian
 193
 194 The Hungarian Notation was conceived by or at least got its name from,
 195 the hungarian programmer Charles Simonyi.  It is a naming convention
 196 with the aim to make code more readable (for fellow programmers), and
 197 more accessible for programmers that are new to a project.
 198
 199 The essence of the Hungarian Notation is that every identifier has a
 200 part which identifies its type (for functions this is the result
 201 type).  This is particularly useful in object oriented programming,
 202 where a particular object implies a specific interface (a set of
 203 member functions, perhaps some redefined operators), and for
 204 accounting heap allocated memory pointers and links.
 205
 206 =head2 Advantages
 207
 208 Another fun quote from Microsoft Secrets:
 209
 210
 211         The Hungarian naming convention gives developers the ability
 212         to read other people's code relatively easily, with a minmum
 213         number of comments in the source code.  Jon De Vann estimated
 214         that only about 1 percent of all lines in the Excel product
 215         code consist of comments, but the code is still very
 216         understandable due to the use of Hungarian: "if you look at
 217         our source code, you also notice very few comments.  Hungarian
 218         gives us the ability to go in and read code..."
 219
 220
 221 Wow! If you use Hungarian you don't have to document your software!
 222 Just think of the hours I have wasted documenting while this "silver bullet"
 223 existed. I feel so stupid and ashamed!
 224
 225 =head2 Disadvantages
 226
 227 =over 5
 228
 229 =item *
 230
 231 more keystrokes (disk space!)
 232
 233 =item *
 234
 235 it looks silly C<get_slu_p()>
 236
 237 =item *
 238
 239 it looks like code from micro suckers
 240
 241 =item *
 242
 243 (which) might scare away some (otherwise good?)
 244 progammers, or make you a paria in the free
 245 software community
 246
 247 =item *
 248
 249 it has ambiguities
 250
 251 =item *
 252
 253 not very useful if not used consistently
 254
 255 =item *
 256
 257 usefullness in I<very large> (but how many classes is very large?)
 258 remains an issue.
 259
 260 =back
 261
 262
 263
 264 =head2 Proposal
 265
 266 =over 5
 267
 268 =item *
 269
 270 learn about cut and paste / use emacs or vi
 271 or lean to type using ten fingers
 272
 273 =item *
 274
 275 Use emacs dabbrev-expand, with dabbrev-case-fold-search set to nil.
 276
 277 =item *
 278
 279 use no, or pick less silly, abbrvs.
 280
 281 =item *
 282
 283 use non-ambiguous postfixes C<identifier_name_type_modifier[_modifier]>
 284
 285 =back
 286
 287 Macros, C<enum>s and C<const>s are all uppercase,
 288 with the parts of the names separated by underscores.
 289
 290 =head2 Types
 291
 292 =over 5
 293
 294 =item C<byte>
 295
 296
 297 unsigned char. (The postfix _by is ambiguous)
 298
 299 =item C<b>
 300
 301
 302 bool
 303
 304 =item C<bi>
 305
 306 bit
 307
 308 =item C<ch>
 309
 310 char
 311
 312 =item C<f>
 313
 314 float
 315
 316 =item C<i>
 317
 318 signed integer
 319
 320 =item C<str>
 321
 322 string class
 323
 324 =item C<sz>
 325
 326 Zero terminated c string
 327
 328 =item C<u>
 329
 330 unsigned integer
 331
 332 =back
 333
 334 =head2 User defined types
 335
 336
 337         /** Slur blah. blah.
 338         (slur)
 339         */
 340         class Slur {};
 341         Slur* slur_p = new Slur;
 342
 343 =head2 Modifiers
 344
 345 The following types modify the meaning of the prefix.
 346 These are precede the prefixes:
 347
 348 =over 5
 349
 350 =item C<a>
 351
 352 array
 353
 354 =item C<array>
 355
 356 user built array.
 357
 358 =item C<c>
 359
 360 const. Note that the proper order C<Type const> i.s.o. C<const Type>
 361
 362 =item C<C>
 363
 364 A const pointer. This would be equivalent to C<_c_l>, but since any
 365 "const" pointer has to be a link (you can't delete a const pointer),
 366 it is superfluous.
 367
 368 =item C<l>
 369
 370 temporary pointer to object (link)
 371
 372 =item C<p>
 373
 374 pointer to newed object
 375
 376 =item C<r>
 377
 378 reference
 379
 380 =back
 381
 382 =over 5
 383
 384 =item C<loop_i>
 385
 386 Variable loop: an integer
 387
 388 =item C<u>
 389
 390 Temporary variable: an unsigned integer
 391
 392 =item C<test_ch>
 393
 394 Variable test: a character
 395
 396 =item C<first_name_str>
 397
 398 Variable first_name: a String class object
 399
 400 =item C<last_name_ch_a>
 401
 402 Variable last_name: a C<char> array
 403
 404 =item C<foo_i_p>
 405
 406 Variable foo: an C<Int*> that you must delete
 407
 408 =item C<bar_i_l>
 409
 410 Variable bar: an C<Int*> that you must not delete
 411
 412 =back
 413
 414 Generally default arguments are taboo, except for nil pointers.
 415
 416 =head1 MISCELLANEOUS
 417
 418 For some tasks, some scripts are supplied, notably creating patches, a
 419 mirror of the website, generating the header to put over cc and hh
 420 files, doing a release.
 421
 422 Use them.
 423
 424 The following generic identifications are used:
 425
 426         up == 1
 427         left == -1
 428         right == 1
 429         down == -1
 430
 431 Intervals are pictured lying on a horizontal numberline (Interval[-1]
 432 is the minimum). The 2D plane has +x on the right, +y pointing up.
 433
 434