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