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