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