Documentation/CodingStyle.pod

   1 =head1 NAME
   2
   3 CodingStyle - standards while programming for GNU LilyPond
   4
   5 =head1 DESCRIPTION
   6
   7 We use these standards while doing programming for GNU LilyPond.  If
   8 you do some hacking, we appreciate it if you would follow this rules,
   9 but if you don't, we still like you.
  10
  11 Functions and methods do not return errorcodes, but use assert for
  12 checking status.
  13
  14 =head2 Quote:
  15
  16 A program should be light and agile, its subroutines
  17 connected like a string of pearls.  The spirit and intent of
  18 the program should be retained throughout.  There should be
  19 neither too little nor too much, neither needless loops nor
  20 useless variables, neither lack of structure nor overwhelming
  21 rigidity.
  22
  23 A program should follow the 'Law of Least
  24 Astonishment'.  What is this law?  It is simply that the
  25 program should always respond to the user in the way that
  26 astonishes him least.
  27
  28 A program, no matter how complex, should act as a
  29 single unit.  The program should be directed by the logic
  30 within rather than by outward appearances.
  31
  32 If the program fails in these requirements, it will be
  33 in a state of disorder and confusion.  The only way to correct
  34 this is to rewrite the program.
  35
  36 -- Geoffrey James, "The Tao of Programming"
  37
  38
  39 =head2 LANGUAGES
  40
  41 C++, /bin/sh and python are preferred.  Perl is not.
  42
  43 =head2 FILES
  44
  45 Definitions of classes that are only accessed via pointers
  46 (*) or references (&) shall not be included as include files.
  47
  48 filenames
  49
  50         ".hh"   Include files
  51         ".cc"   Implementation files
  52         ".icc"  Inline definition files
  53         ".tcc"  non inline Template defs
  54
  55 in emacs:
  56
  57         (setq auto-mode-alist
  58               (append '(("\\.make$" . makefile-mode)
  59                         ("\\.cc$" . c++-mode)
  60                         ("\\.icc$" . c++-mode)
  61                         ("\\.tcc$" . c++-mode)
  62                         ("\\.hh$" . c++-mode)
  63                         ("\\.pod$" . text-mode)
  64                         )
  65                       auto-mode-alist))
  66
  67
  68 The class Class_name_abbreviation is coded in F<class-name-abbr.*>
  69
  70
  71 =head2 INDENTATION
  72
  73 in emacs:
  74
  75
  76         (add-hook 'c++-mode-hook
  77                   '(lambda() (c-set-style "gnu")
  78                      )
  79                   )
  80
  81 If you like using font-lock, you can also add this to your F<.emacs>:
  82
  83         (setq font-lock-maximum-decoration t)
  84         (setq c++-font-lock-keywords-3
  85               (append
  86                c++-font-lock-keywords-3
  87                '(("\\b\\([a-zA-Z_]+_\\)\\b" 1 font-lock-variable-name-face)
  88                ("\\b\\([A-Z]+[a-z_]+\\)\\b" 1 font-lock-type-face))
  89                ))
  90
  91 =head2 CLASSES and TYPES:
  92
  93         This_is_a_class
  94         AClass_name     (for Abbreviation_class_name)
  95
  96 =head2 MEMBERS
  97
  98         Class::member()
  99         Type Class::member_type_
 100         Type Class::member_type()
 101
 102 the C<type> is a Hungarian notation postfix for C<Type>. See below
 103
 104 =head2 MACROS
 105
 106 Macros should be written completely in uppercase
 107
 108 The code should not be compilable if proper macro declarations are not
 109 included.
 110
 111 Don't laugh. It took us a whole evening/night to figure out one of
 112 these bugs.
 113
 114 =head2 BROKEN CODE
 115
 116 Broken code (hardwired dependencies, hardwired constants, slow
 117 algorithms and obvious limitations) should be marked as such:
 118 either with a verbose TODO, or with a short "ugh" comment.
 119
 120 =head2 COMMENTS
 121
 122 The source is commented in the DOC++ style.  Check out doc++ at
 123 http://www.zib.de/Visual/software/doc++/index.html
 124
 125         /*
 126                 C style comments for multiline comments.
 127                 They come before the thing to document.
 128                 [...]
 129         */
 130
 131
 132         /**
 133                 short description.
 134                 Long class documentation.
 135                 (Hungarian postfix)
 136
 137                 TODO Fix boring_member()
 138         */
 139         class Class {
 140                 /**
 141                   short description.
 142                   long description
 143                 */
 144
 145                 Data data_member_;
 146
 147
 148                 /**
 149                         short memo. long doco of member()
 150                         @param description of arguments
 151                         @return Rettype
 152                 */
 153                 Rettype member(Argtype);
 154
 155                 /// memo only
 156                 boring_member() {
 157                         data_member_ = 121; // ugh
 158                 }
 159         };
 160
 161
 162
 163 Unfortunately most of the code isn't really documented that good.
 164
 165
 166 =head2 MEMBERS (2)
 167
 168 Standard methods:
 169
 170         ///check that *this satisfies its invariants, abort if not.
 171         void OK() const
 172
 173         /// print *this (and substructures) to debugging log
 174         void print() const
 175
 176         /**
 177         protected member. Usually invoked by non-virtual XXXX()
 178         */
 179         virtual do_XXXX()
 180
 181         /**add some data to *this.
 182         Presence of these methods usually imply that it is not feasible to this
 183         via  a constructor
 184         */
 185         add (..)
 186
 187         /// replace some data of *this
 188         set (..)
 189
 190 =head2 Constructor
 191
 192 Every class should have a default constructor.
 193
 194 Don't use non-default constructors if this can be avoided:
 195
 196         Foo f(1)
 197
 198 is less readable than
 199
 200         Foo f;
 201         f.x = 1
 202
 203 or
 204         Foo f(Foo_convert::int_to_foo (1))
 205
 206
 207
 208 =head1 HUNGARIAN NOTATION NAMING CONVENTION
 209
 210 Proposed is a naming convention derived from the so-called I<Hungarian
 211 Notation>.
 212
 213 =head2 Hungarian
 214
 215 The Hungarian Notation was conceived by or at least got its name from,
 216 the hungarian programmer Charles Simonyi.  It is a naming convention
 217 with the aim to make code more readable (for fellow programmers), and
 218 more accessible for programmers that are new to a project.
 219
 220 The essence of the Hungarian Notation is that every identifier has a
 221 part which identifies its type (for functions this is the result
 222 type).  This is particularly useful in object oriented programming,
 223 where a particular object implies a specific interface (a set of
 224 member functions, perhaps some redefined operators), and for
 225 accounting heap allocated memory pointers and links.
 226
 227 =head2 Advantages
 228
 229 Another fun quote from Microsoft Secrets:
 230
 231
 232         The Hungarian naming convention gives developers the ability
 233         to read other people's code relatively easily, with a minmum
 234         number of comments in the source code.  Jon De Vann estimated
 235         that only about 1 percent of all lines in the Excel product
 236         code consist of comments, but the code is still very
 237         understandable due to the use of Hungarian: "if you look at
 238         our source code, you also notice very few comments.  Hungarian
 239         gives us the ability to go in and read code..."
 240
 241 Wow! If you use Hungarian you don't have to document your software!
 242 Just think of the hours I have wasted documenting while this "silver bullet"
 243 existed. I feel so stupid and ashamed!  [Didn't MMM-Brooks say `There is
 244 no silver bullet?' --HWN]
 245
 246
 247 =head2 Disadvantages
 248
 249 =over 5
 250
 251 =item *
 252
 253 more keystrokes (disk space!)
 254
 255 =item *
 256
 257 it looks silly C<get_slu_p()>
 258
 259 =item *
 260
 261 it looks like code from micro suckers
 262
 263 =item *
 264
 265 (which) might scare away some (otherwise good?)
 266 progammers, or make you a paria in the free
 267 software community
 268
 269 =item *
 270
 271 it has ambiguities
 272
 273 =item *
 274
 275 not very useful if not used consistently
 276
 277 =item *
 278
 279 usefullness in I<very large> (but how many classes is very large?)
 280 remains an issue.
 281
 282 =back
 283
 284
 285
 286 =head2 Proposal
 287
 288 =over 5
 289
 290 =item *
 291
 292 learn about cut and paste / use emacs or vi
 293 or lean to type using ten fingers
 294
 295 =item *
 296
 297 Use emacs dabbrev-expand, with dabbrev-case-fold-search set to nil.
 298
 299 =item *
 300
 301 use no, or pick less silly, abbrvs.
 302
 303 =item *
 304
 305 use non-ambiguous postfixes C<identifier_name_type_modifier[_modifier]>
 306
 307 =item *
 308
 309 There is no need for Hungarian if the scope of the variable is small,
 310 ie. local variables, arguments in function definitions (not
 311 declarations).
 312
 313 =back
 314
 315 Macros, C<enum>s and C<const>s are all uppercase,
 316 with the parts of the names separated by underscores.
 317
 318 =head2 Types
 319
 320 =over 5
 321
 322 =item C<byte>
 323
 324
 325 unsigned char. (The postfix _by is ambiguous)
 326
 327 =item C<b>
 328
 329
 330 bool
 331
 332 =item C<bi>
 333
 334 bit
 335
 336 =item C<ch>
 337
 338 char
 339
 340 =item C<f>
 341
 342 float
 343
 344 =item C<i>
 345
 346 signed integer
 347
 348 =item C<str>
 349
 350 string class
 351
 352 =item C<sz>
 353
 354 Zero terminated c string
 355
 356 =item C<u>
 357
 358 unsigned integer
 359
 360 =back
 361
 362 =head2 User defined types
 363
 364
 365         /** Slur blah. blah.
 366         (slur)
 367         */
 368         class Slur {};
 369         Slur* slur_p = new Slur;
 370
 371 =head2 Modifiers
 372
 373 The following types modify the meaning of the prefix.
 374 These are preceded by the prefixes:
 375
 376 =over 5
 377
 378 =item C<a>
 379
 380 array
 381
 382 =item C<array>
 383
 384 user built array.
 385
 386 =item C<c>
 387
 388 const. Note that the proper order is C<Type const> i.s.o. C<const Type>
 389
 390 =item C<C>
 391
 392 A const pointer. This would be equivalent to C<_c_l>, but since any
 393 "const" pointer has to be a link (you can't delete a const pointer),
 394 it is superfluous.
 395
 396 =item C<l>
 397
 398 temporary pointer to object (link)
 399
 400 =item C<p>
 401
 402 pointer to newed object
 403
 404 =item C<r>
 405
 406 reference
 407
 408 =back
 409
 410 =over 5
 411
 412 =head2 Adjective
 413
 414 Adjectives such as global and static should be spelled out in full.
 415 They come before the noun that they refer to, just as in normal english.
 416
 417 foo_global_i: a global variable of type int commonly called "foo".
 418
 419 static class members do not need the static_ prefix in the name (the
 420 Class::var notation usually makes it clear that it is static)
 421
 422 =item C<loop_i>
 423
 424 Variable loop: an integer
 425
 426 =item C<u>
 427
 428 Temporary variable: an unsigned integer
 429
 430 =item C<test_ch>
 431
 432 Variable test: a character
 433
 434 =item C<first_name_str>
 435
 436 Variable first_name: a String class object
 437
 438 =item C<last_name_ch_a>
 439
 440 Variable last_name: a C<char> array
 441
 442 =item C<foo_i_p>
 443
 444 Variable foo: an C<Int*> that you must delete
 445
 446 =item C<bar_i_l>
 447
 448 Variable bar: an C<Int*> that you must not delete
 449
 450 =back
 451
 452 Generally default arguments are taboo, except for nil pointers.
 453
 454 The naming convention can be quite conveniently memorised, by
 455 expressing the type in english, and abbreviating it
 456
 457         static Array<int*> foo
 458
 459 C<foo> can be described as "the static int-pointer user-array", so you get
 460
 461         foo_static_l_arr
 462
 463
 464
 465
 466 =head1 MISCELLANEOUS
 467
 468 For some tasks, some scripts are supplied, notably creating patches, a
 469 mirror of the website, generating the header to put over cc and hh
 470 files, doing a release.
 471
 472 Use them.
 473
 474 The following generic identifications are used:
 475
 476         up == 1
 477         left == -1
 478         right == 1
 479         down == -1
 480
 481 Intervals are pictured lying on a horizontal numberline (Interval[-1]
 482 is the minimum). The 2D plane has +x on the right, +y pointing up.
 483
 484