Documentation/CodingStyle.pod

   1 =head1 NAME
   2
   3 CodingStyle - standards while programming for LilyPond
   4
   5 =head1 DESCRIPTION
   6
   7 Please use these standards while doing programming for 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 Template include files always have the file name extension ".tcc".
  49
  50
  51 =head2 INDENTATION
  52
  53 in emacs:
  54
  55
  56         (add-hook 'c-mode-hook
  57                   '(lambda ()(setq c-basic-offset 4)))
  58
  59
  60         (add-hook 'c++-mode-hook
  61                   '(lambda() (c-set-style "Stroustrup")
  62                      )
  63                   )
  64
  65
  66 =head2 CLASSES and TYPES:
  67
  68         This_is_a_class
  69         AClass_name     (for Abbreviation_class_name)
  70
  71 =head2 DATA MEMBERS
  72
  73         Class::member()
  74         Type Class::member_type_
  75
  76 the C<type> is a Hungarian notation postfix for C<Type>. See below
  77
  78
  79 =head2 COMMENTS
  80
  81 The source is commented in the DOC++ style.  Check out doc++ at
  82 http://www.zib.de/Visual/software/doc++/index.html
  83
  84         /*
  85                 C style comments for multiline comments.
  86                 [...]
  87         */
  88
  89
  90         /**
  91                 short description.
  92                 Long class documentation.
  93                 (Hungarian postfix)
  94         */
  95         class Class {
  96                 /**
  97                   short description.
  98                   long description
  99                 */
 100
 101                 Data data_member_;
 102
 103
 104                 /**
 105                         short memo. long doco of member()
 106                         @param description of arguments
 107                         @return Rettype
 108                 */
 109                 Rettype member(Argtype);
 110
 111                 /// memo only
 112                 boring_member();
 113         };
 114
 115 Unfortunately most of the code isn't really documented that good.
 116
 117
 118 =head2 CLASSNAMES (2)
 119
 120 A lot of classes in LilyPond start with 'P', this is to distinguish
 121 certain parts of LilyPond: the P stands for Printer, and the P-classes
 122 are supposed to be more lowlevel than the others. Example:
 123
 124 Staff uses PStaff, PScore and PCol to do the typesetting of
 125 symbols. Staff is  the "brains" for PStaff
 126
 127 NB: in PCursor (which is part of the library) P stands for PointerCursor
 128
 129
 130 =head2 MEMBERS (2)
 131
 132 Standard methods:
 133
 134         ///check that *this satisfies its invariants, abort if not.
 135         void OK() const
 136
 137         /// print *this (and substructures) to debugging log
 138         void print() const
 139
 140         /**
 141         protected member. Usually invoked by non-virtual XXXX()
 142         */
 143         virtual do_XXXX()
 144
 145         /**add some data to *this.
 146         Presence of these methods usually imply that it is not feasible to this
 147         via  a constructor
 148         */
 149         add( .. )
 150
 151         /// replace some data of *this
 152         set( .. )
 153
 154 =head1 HUNGARIAN NOTATION NAMING CONVENTION
 155
 156 Proposed is a naming convention derived from the so-called I<Hungarian
 157 Notation>.
 158
 159 =head2 Hungarian
 160
 161 The Hungarian Notation was conceived by or at least got its name from,
 162 the hungarian programmer Charles Simonyi.  It is a naming convention
 163 with the aim to make code more readable (for fellow programmers), and
 164 more accessible for programmers that are new to a project.
 165
 166 The essence of the Hungarian Notation is that every identifier has a
 167 part which identifies its type (for functions this is the result
 168 type).  This is particularly useful in object oriented programming,
 169 where a particular object implies a specific interface (a set of
 170 member functions, perhaps some redefined operators), and for
 171 accounting heap allocated memory pointers and links.
 172
 173 =head2 Advantages
 174
 175 Another fun quote from Microsoft Secrets:
 176
 177
 178         The Hungarian naming convention gives developers the ability
 179         to read other people's code relatively easily, with a minmum
 180         number of comments in the source code.  Jon De Vann estimated
 181         that only about 1 percent of all lines in the Excel product
 182         code consist of comments, but the code is still very
 183         understandable due to the use of Hungarian: "if you look at
 184         our source code, you also notice very few comments.  Hungarian
 185         gives us the ability to go in and read code..."
 186
 187
 188 Wow! If you use Hungarian you don't have to document your software!
 189 Just think of the hours I have wasted documenting while this "silver bullet"
 190 existed. I feel so stupid and ashamed!
 191
 192 =head2 Disadvantages
 193
 194 =over 4
 195
 196 =item *
 197
 198 more keystrokes (disk space!)
 199
 200 =item *
 201
 202 it looks silly C<get_slu_p()>
 203
 204 =item *
 205
 206 it looks like code from micro suckers
 207
 208 =item *
 209
 210 (which) might scare away some (otherwise good?)
 211 progammers, or make you a paria in the free
 212 software community
 213
 214 =item *
 215
 216 it has ambiguities
 217
 218 =item *
 219
 220 not very useful if not used consistently
 221
 222 =item *
 223
 224 usefullness in I<very large>
 225 (but how many classes is very large?)
 226 remains an issue.
 227
 228 =back
 229
 230
 231
 232 =head2 Proposal
 233
 234 =over 4
 235
 236 =item *
 237
 238 learn about cut and paste / use emacs or vi
 239 or lean to type using ten fingers
 240
 241 =item *
 242
 243 Use emacs dabbrev-expand, with dabbrev-case-fold-search set to nil.
 244
 245 =item *
 246
 247 use no, or pick less silly, abbrvs.
 248
 249 =item *
 250
 251 use non-ambiguous postfixes C<identifier_name_type_modifier[_modifier]>
 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 4
 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 4
 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 4
 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