Documentation/CodingStyle.pod

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