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                 A program should be light and agile, its subroutines
  13         connected like a strings of pearls.  The spirit and intent of
  14         the program should be retained throughout.  There should be
  15         neither too little nor too much, neither needless loops nor
  16         useless variables, neither lack of structure nor overwhelming
  17         rigidity.
  18
  19                 A program should follow the 'Law of Least
  20         Astonishment'.  What is this law?  It is simply that the
  21         program should always respond to the user in the way that
  22         astonishes him least.
  23
  24                 A program, no matter how complex, should act as a
  25         single unit.  The program should be directed by the logic
  26         within rather than by outward appearances.
  27
  28                 If the program fails in these requirements, it will be
  29         in a state of disorder and confusion.  The only way to correct
  30         this is to rewrite the program.
  31                 -- Geoffrey James, "The Tao of Programming"
  32
  33 =head2 INDENTATION
  34
  35 in emacs:
  36
  37
  38         (add-hook 'c-mode-hook
  39                   '(lambda ()(setq c-basic-offset 4)))
  40
  41
  42         (add-hook 'c++-mode-hook
  43                   '(lambda() (c-set-style "Stroustrup")
  44                      )
  45                   )
  46
  47
  48 =head2 CLASSES and TYPES:
  49
  50         This_is_a_class
  51         AClass_name     (for Abbreviation_class_name)
  52
  53 =head2 DATA MEMBERS
  54
  55         Class::member()
  56         Type Class::member_type_
  57
  58 the C<type> is a Hungarian notation postfix for $C<Type>$. See below
  59
  60
  61 =head2 COMMENTS
  62
  63 The source is commented in the DOC++ style.  Check out doc++ at
  64 http://www.zib.de/Visual/software/doc++/index.html
  65
  66         /*
  67                 C style comments for multiline comments.
  68                 [...]
  69         */
  70
  71
  72         /**
  73                 short description.
  74                 Long class documentation.
  75                 (Hungarian postfix)
  76         */
  77         class Class {
  78                 /**
  79                   short description.
  80                   long description
  81                 */
  82
  83                 Data data_member_;
  84
  85
  86                 /**
  87                         short memo. long doco of member()
  88                         @param description of arguments
  89                         @return Rettype
  90                 */
  91                 Rettype member(Argtype);
  92
  93                 /// memo only
  94                 boring_member();
  95         };
  96
  97 Unfortunately most of the code isn't really documented that good.
  98
  99
 100 =head2 CLASSNAMES (2)
 101
 102 A lot of classes in LilyPond start with 'P', this is to distinguish
 103 certain parts of LilyPond: the P stands for Printer, and the P-classes
 104 are supposed to be more lowlevel than the others. Example:
 105
 106 Staff uses PStaff, PScore and PCol to do the typesetting of
 107 symbols. Staff is  the "brains" for PStaff
 108
 109 NB: in PCursor (which is part of the library) P stands for PointerCursor
 110
 111
 112 =head2 MEMBERS(2)
 113
 114 Standard methods:
 115
 116         ///check that *this satisfies its invariants, abort if not.
 117         void OK() const
 118
 119         /// print *this (and substructures) to debugging log
 120         void print() const
 121
 122         /**
 123         protected member. Usually invoked by non-virtual XXXX()
 124         */
 125         virtual do_XXXX()
 126
 127         /**add some data to *this.
 128         Presence of these methods usually imply that it is not feasible to this
 129         via  a constructor
 130         */
 131         add( .. )
 132
 133         /// replace some data of *this
 134         set( .. )
 135
 136 =head1 HUNGARIAN NOTATION NAMING CONVENTION
 137
 138 Proposed is a naming convention derived from the so-called I<Hungarian
 139 Notation>.
 140
 141 =head2 Hungarian
 142
 143 The Hungarian Notation was conceived by or at least got its name from,
 144 the hungarian programmer Charles Simonyi.  It is a naming convention
 145 with the aim to make code more readable (for fellow programmers), and
 146 more accessible for programmers that are new to a project.
 147
 148 The essence of the Hungarian Notation is that every identifier has a
 149 part which identifies its type (for functions this is the result
 150 type).  This is particularly useful in object oriented programming,
 151 where a particular object implies a specific interface (a set of
 152 member functions, perhaps some redefined operators), and for
 153 accounting heap allocated memory pointers and links.
 154
 155 =head2 Advantages
 156
 157 Another fun quote from Microsoft Secrets:
 158
 159
 160         The Hungarian naming convention gives developers the ability
 161         to read other people's code relatively easily, with a minmum
 162         number of comments in the source code.  Jon De Vann estimated
 163         that only about 1 percent of all lines in the Excel product
 164         code consist of comments, but the code is still very
 165         understandable due to the use of Hungarian: "if you look at
 166         our source code, you also notice very few comments.  Hungarian
 167         gives us the ability to go in and read code..."
 168
 169
 170 Wow! If you use Hungarian you don't have to document your software!
 171 Just think of the hours I have wasted documenting while this "silver bullet"
 172 existed. I feel so stupid and ashamed!
 173
 174 =head2 Disadvantages
 175
 176 =over 5
 177
 178 =item *
 179 more keystrokes (disk space!)
 180
 181 =item *
 182 it looks silly C<get_slu_p()>
 183
 184 =item *
 185 it looks like code from micro suckers
 186
 187 =item *
 188 (which) might scare away some (otherwise good?)
 189 progammers, or make you a paria in the free
 190 software community
 191
 192 =item *
 193 it has ambiguities
 194
 195 =item *
 196 not very useful if not used consistently
 197
 198 =item *
 199 usefullness in I<very large>
 200 (but how many classes is very large?)
 201 remains an issue.
 202
 203 =back
 204
 205
 206
 207 =head2 Proposal
 208
 209 =over 5
 210
 211 =item *
 212 learn about cut and paste / use emacs or vi
 213 or lean to type using ten fingers
 214
 215 =item *
 216 Use emacs dabbrev-expand, with dabbrev-case-fold-search set to nil.
 217
 218 =item *
 219 use no, or pick less silly, abbrvs.
 220
 221 =item *
 222 use non-ambiguous postfixes C<identifier_name_type_modifier[_modifier]>
 223 =back
 224
 225 Macros, C<enum>s and C<const>s are all uppercase,
 226 with the parts of the names separated by underscores.
 227
 228 =head2 Types
 229
 230 =over 5
 231
 232 =item C<byte>
 233 unsigned char. (The postfix _by is ambiguous)
 234
 235 =item C<b>
 236 bool
 237
 238 =item C<bi>
 239 bit
 240
 241 =item C<ch>
 242 char
 243
 244 =item C<f>
 245 float
 246
 247 =item C<i>
 248 signed integer
 249
 250 =item C<str>
 251 string class
 252
 253 =item C<sz>
 254 Zero terminated c string
 255
 256 =item C<u>
 257 unsigned integer
 258
 259 =back
 260
 261 =head2 User defined types
 262
 263
 264         /** Slur blah. blah.
 265         (slur)
 266         */
 267         class Slur {};
 268         Slur* slur_p = new Slur;
 269
 270 =head2 Modifiers
 271
 272 The following types modify the meaning of the prefix.
 273 These are precede the prefixes:
 274
 275 =over 5
 276
 277 =item C<a>
 278 array
 279
 280 =item C<array>
 281 user built array.
 282
 283 =item C<c>
 284 const
 285
 286 =item C<l>
 287 temporary pointer to object (link)
 288
 289 =item C<p>
 290 pointer to newed object
 291
 292 =item C<r>
 293 reference
 294
 295 =back
 296
 297 =over 5
 298
 299 =item C<loop_i>
 300 Variable loop: an integer
 301
 302 =item C<u>
 303 Temporary variable: an unsigned integer
 304
 305 =item C<test_ch>
 306 Variable test: a character
 307
 308 =item C<first_name_str>
 309 Variable first_name: a String class object
 310
 311 =item C<last_name_ch_a>
 312 Variable last_name: a C<char> array
 313
 314 =item C<foo_i_p>
 315 Variable foo: an C<Int*> that you must delete
 316
 317 =item C<bar_i_l>
 318 Variable bar: an C<Int*> that you must not delete
 319
 320 =back
 321
 322
 323