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 =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 Wow! If you use Hungarian you don't have to document your software!
 221 Just think of the hours I have wasted documenting while this "silver bullet"
 222 existed. I feel so stupid and ashamed!  [Didn't MMM-Brooks say `There is
 223 no silver bullet?' --HWN]
 224
 225
 226 =head2 Disadvantages
 227
 228 =over 5
 229
 230 =item *
 231
 232 more keystrokes (disk space!)
 233
 234 =item *
 235
 236 it looks silly C<get_slu_p()>
 237
 238 =item *
 239
 240 it looks like code from micro suckers
 241
 242 =item *
 243
 244 (which) might scare away some (otherwise good?)
 245 progammers, or make you a paria in the free
 246 software community
 247
 248 =item *
 249
 250 it has ambiguities
 251
 252 =item *
 253
 254 not very useful if not used consistently
 255
 256 =item *
 257
 258 usefullness in I<very large> (but how many classes is very large?)
 259 remains an issue.
 260
 261 =back
 262
 263
 264
 265 =head2 Proposal
 266
 267 =over 5
 268
 269 =item *
 270
 271 learn about cut and paste / use emacs or vi
 272 or lean to type using ten fingers
 273
 274 =item *
 275
 276 Use emacs dabbrev-expand, with dabbrev-case-fold-search set to nil.
 277
 278 =item *
 279
 280 use no, or pick less silly, abbrvs.
 281
 282 =item *
 283
 284 use non-ambiguous postfixes C<identifier_name_type_modifier[_modifier]>
 285
 286 =back
 287
 288 Macros, C<enum>s and C<const>s are all uppercase,
 289 with the parts of the names separated by underscores.
 290
 291 =head2 Types
 292
 293 =over 5
 294
 295 =item C<byte>
 296
 297
 298 unsigned char. (The postfix _by is ambiguous)
 299
 300 =item C<b>
 301
 302
 303 bool
 304
 305 =item C<bi>
 306
 307 bit
 308
 309 =item C<ch>
 310
 311 char
 312
 313 =item C<f>
 314
 315 float
 316
 317 =item C<i>
 318
 319 signed integer
 320
 321 =item C<str>
 322
 323 string class
 324
 325 =item C<sz>
 326
 327 Zero terminated c string
 328
 329 =item C<u>
 330
 331 unsigned integer
 332
 333 =back
 334
 335 =head2 User defined types
 336
 337
 338         /** Slur blah. blah.
 339         (slur)
 340         */
 341         class Slur {};
 342         Slur* slur_p = new Slur;
 343
 344 =head2 Modifiers
 345
 346 The following types modify the meaning of the prefix.
 347 These are preceded by the prefixes:
 348
 349 =over 5
 350
 351 =item C<a>
 352
 353 array
 354
 355 =item C<array>
 356
 357 user built array.
 358
 359 =item C<c>
 360
 361 const. Note that the proper order is C<Type const> i.s.o. C<const Type>
 362
 363 =item C<C>
 364
 365 A const pointer. This would be equivalent to C<_c_l>, but since any
 366 "const" pointer has to be a link (you can't delete a const pointer),
 367 it is superfluous.
 368
 369 =item C<l>
 370
 371 temporary pointer to object (link)
 372
 373 =item C<p>
 374
 375 pointer to newed object
 376
 377 =item C<r>
 378
 379 reference
 380
 381 =back
 382
 383 =over 5
 384
 385 =item C<loop_i>
 386
 387 Variable loop: an integer
 388
 389 =item C<u>
 390
 391 Temporary variable: an unsigned integer
 392
 393 =item C<test_ch>
 394
 395 Variable test: a character
 396
 397 =item C<first_name_str>
 398
 399 Variable first_name: a String class object
 400
 401 =item C<last_name_ch_a>
 402
 403 Variable last_name: a C<char> array
 404
 405 =item C<foo_i_p>
 406
 407 Variable foo: an C<Int*> that you must delete
 408
 409 =item C<bar_i_l>
 410
 411 Variable bar: an C<Int*> that you must not delete
 412
 413 =back
 414
 415 Generally default arguments are taboo, except for nil pointers.
 416
 417 =head1 MISCELLANEOUS
 418
 419 For some tasks, some scripts are supplied, notably creating patches, a
 420 mirror of the website, generating the header to put over cc and hh
 421 files, doing a release.
 422
 423 Use them.
 424
 425 The following generic identifications are used:
 426
 427         up == 1
 428         left == -1
 429         right == 1
 430         down == -1
 431
 432 Intervals are pictured lying on a horizontal numberline (Interval[-1]
 433 is the minimum). The 2D plane has +x on the right, +y pointing up.
 434
 435