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