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