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