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