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