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