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 =head2 MACROS
 101
 102 The code should not be compilable if proper macro declarations are not
 103 included.
 104
 105 Don't laugh. It took us a whole figure out one of 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 =head1 HUNGARIAN NOTATION NAMING CONVENTION
 184
 185 Proposed is a naming convention derived from the so-called I<Hungarian
 186 Notation>.
 187
 188 =head2 Hungarian
 189
 190 The Hungarian Notation was conceived by or at least got its name from,
 191 the hungarian programmer Charles Simonyi.  It is a naming convention
 192 with the aim to make code more readable (for fellow programmers), and
 193 more accessible for programmers that are new to a project.
 194
 195 The essence of the Hungarian Notation is that every identifier has a
 196 part which identifies its type (for functions this is the result
 197 type).  This is particularly useful in object oriented programming,
 198 where a particular object implies a specific interface (a set of
 199 member functions, perhaps some redefined operators), and for
 200 accounting heap allocated memory pointers and links.
 201
 202 =head2 Advantages
 203
 204 Another fun quote from Microsoft Secrets:
 205
 206
 207         The Hungarian naming convention gives developers the ability
 208         to read other people's code relatively easily, with a minmum
 209         number of comments in the source code.  Jon De Vann estimated
 210         that only about 1 percent of all lines in the Excel product
 211         code consist of comments, but the code is still very
 212         understandable due to the use of Hungarian: "if you look at
 213         our source code, you also notice very few comments.  Hungarian
 214         gives us the ability to go in and read code..."
 215
 216
 217 Wow! If you use Hungarian you don't have to document your software!
 218 Just think of the hours I have wasted documenting while this "silver bullet"
 219 existed. I feel so stupid and ashamed!
 220
 221 =head2 Disadvantages
 222
 223 =over 5
 224
 225 =item *
 226
 227 more keystrokes (disk space!)
 228
 229 =item *
 230
 231 it looks silly C<get_slu_p()>
 232
 233 =item *
 234
 235 it looks like code from micro suckers
 236
 237 =item *
 238
 239 (which) might scare away some (otherwise good?)
 240 progammers, or make you a paria in the free
 241 software community
 242
 243 =item *
 244
 245 it has ambiguities
 246
 247 =item *
 248
 249 not very useful if not used consistently
 250
 251 =item *
 252
 253 usefullness in I<very large> (but how many classes is very large?)
 254 remains an issue.
 255
 256 =back
 257
 258
 259
 260 =head2 Proposal
 261
 262 =over 5
 263
 264 =item *
 265
 266 learn about cut and paste / use emacs or vi
 267 or lean to type using ten fingers
 268
 269 =item *
 270
 271 Use emacs dabbrev-expand, with dabbrev-case-fold-search set to nil.
 272
 273 =item *
 274
 275 use no, or pick less silly, abbrvs.
 276
 277 =item *
 278
 279 use non-ambiguous postfixes C<identifier_name_type_modifier[_modifier]>
 280
 281 =back
 282
 283 Macros, C<enum>s and C<const>s are all uppercase,
 284 with the parts of the names separated by underscores.
 285
 286 =head2 Types
 287
 288 =over 5
 289
 290 =item C<byte>
 291
 292
 293 unsigned char. (The postfix _by is ambiguous)
 294
 295 =item C<b>
 296
 297
 298 bool
 299
 300 =item C<bi>
 301
 302 bit
 303
 304 =item C<ch>
 305
 306 char
 307
 308 =item C<f>
 309
 310 float
 311
 312 =item C<i>
 313
 314 signed integer
 315
 316 =item C<str>
 317
 318 string class
 319
 320 =item C<sz>
 321
 322 Zero terminated c string
 323
 324 =item C<u>
 325
 326 unsigned integer
 327
 328 =back
 329
 330 =head2 User defined types
 331
 332
 333         /** Slur blah. blah.
 334         (slur)
 335         */
 336         class Slur {};
 337         Slur* slur_p = new Slur;
 338
 339 =head2 Modifiers
 340
 341 The following types modify the meaning of the prefix.
 342 These are precede the prefixes:
 343
 344 =over 5
 345
 346 =item C<a>
 347
 348 array
 349
 350 =item C<array>
 351
 352 user built array.
 353
 354 =item C<c>
 355
 356 const. Note that the proper order C<Type const> i.s.o. C<const Type>
 357
 358 =item C<C>
 359
 360 A const pointer. This would be equivalent to C<_c_l>, but since any
 361 "const" pointer has to be a link (you can't delete a const pointer),
 362 it is superfluous.
 363
 364 =item C<l>
 365
 366 temporary pointer to object (link)
 367
 368 =item C<p>
 369
 370 pointer to newed object
 371
 372 =item C<r>
 373
 374 reference
 375
 376 =back
 377
 378 =over 5
 379
 380 =item C<loop_i>
 381
 382 Variable loop: an integer
 383
 384 =item C<u>
 385
 386 Temporary variable: an unsigned integer
 387
 388 =item C<test_ch>
 389
 390 Variable test: a character
 391
 392 =item C<first_name_str>
 393
 394 Variable first_name: a String class object
 395
 396 =item C<last_name_ch_a>
 397
 398 Variable last_name: a C<char> array
 399
 400 =item C<foo_i_p>
 401
 402 Variable foo: an C<Int*> that you must delete
 403
 404 =item C<bar_i_l>
 405
 406 Variable bar: an C<Int*> that you must not delete
 407
 408 =back
 409
 410 Generally default arguments are taboo, except for nil pointers.
 411
 412 =head1 MISCELLANEOUS
 413
 414 For some tasks, some scripts are supplied, notably creating patches, a
 415 mirror of the website, generating the header to put over cc and hh
 416 files, doing a release.
 417
 418 Use them.
 419
 420 The following generic identifications are used:
 421
 422         up == 1
 423         left == -1
 424         right == 1
 425         down == -1
 426
 427 Intervals are pictured lying on a horizontal numberline (Interval[-1]
 428 is the minimum). The 2D plane has +x on the right, +y pointing up.
 429
 430