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