partial: 1.0.1.jcn

[lilypond.git] / Documentation / CodingStyle.pod

diff --git a/Documentation/CodingStyle.pod b/Documentation/CodingStyle.pod
index 7fe901c18650f84b83b5c696a5360dcdd61e2386..0f57d3e1b31bd48a60b019cf6bd519bad4a50105 100644 (file)
--- a/Documentation/CodingStyle.pod
+++ b/Documentation/CodingStyle.pod
@@ -4,7 +4,9 @@ CodingStyle - standards while programming for GNU LilyPond
 
 =head1 DESCRIPTION
 
-Please use these standards while doing programming for GNU LilyPond
+We use these standards while doing programming for GNU LilyPond.  If
+you do some hacking, we appreciate it if you would follow this rules,
+but if you don't, we still like you.
 
 Functions and methods do not return errorcodes, but use assert for
 checking status. 
@@ -33,6 +35,11 @@ this is to rewrite the program.
 
 -- Geoffrey James, "The Tao of Programming"
 
+
+=head2 LANGUAGES
+
+C++, /bin/sh and python are preferred.  Perl is not.
+
 =head2 FILES
 
 Definitions of classes that are only accessed via pointers
@@ -66,12 +73,8 @@ The class Class_name_abbreviation is coded in F<class-name-abbr.*>
 in emacs:
 
 
-       (add-hook 'c-mode-hook
-                 '(lambda ()(setq c-basic-offset 4)))
-
-
        (add-hook 'c++-mode-hook
-                 '(lambda() (c-set-style "Stroustrup")
+                 '(lambda() (c-set-style "gnu")
                     )
                  )
 
@@ -90,16 +93,23 @@ If you like using font-lock, you can also add this to your F<.emacs>:
        This_is_a_class
        AClass_name     (for Abbreviation_class_name)
 
-=head2 DATA MEMBERS
+=head2 MEMBERS
 
        Class::member()
        Type Class::member_type_
+       Type Class::member_type()
 
 the C<type> is a Hungarian notation postfix for C<Type>. See below
 
 =head2 MACROS
 
+Macros should be written completely in uppercase
+
+The code should not be compilable if proper macro declarations are not
+included. 
 
+Don't laugh. It took us a whole evening/night to figure out one of
+these bugs.
 
 =head2 BROKEN CODE
 
@@ -172,10 +182,28 @@ Standard methods:
        Presence of these methods usually imply that it is not feasible to this
        via  a constructor
        */
-       add( .. )
+       add (..)
 
        /// replace some data of *this
-       set( .. )
+       set (..)
+
+=head2 Constructor
+
+Every class should have a default constructor.  
+
+Don't use non-default constructors if this can be avoided:
+
+       Foo f(1)
+
+is less readable than
+
+       Foo f;
+       f.x = 1
+
+or 
+       Foo f(Foo_convert::int_to_foo (1))
+
+
 
 =head1 HUNGARIAN NOTATION NAMING CONVENTION
 
@@ -210,10 +238,11 @@ Another fun quote from Microsoft Secrets:
        our source code, you also notice very few comments.  Hungarian
        gives us the ability to go in and read code..."
 
-
 Wow! If you use Hungarian you don't have to document your software!
 Just think of the hours I have wasted documenting while this "silver bullet"
-existed. I feel so stupid and ashamed!
+existed. I feel so stupid and ashamed!  [Didn't MMM-Brooks say `There is
+no silver bullet?' --HWN]
+
 
 =head2 Disadvantages
 
@@ -275,6 +304,12 @@ use no, or pick less silly, abbrvs.
 
 use non-ambiguous postfixes C<identifier_name_type_modifier[_modifier]>
 
+=item *
+
+There is no need for Hungarian if the scope of the variable is small,
+ie. local variables, arguments in function definitions (not
+declarations).
+
 =back
 
 Macros, C<enum>s and C<const>s are all uppercase,
@@ -336,7 +371,7 @@ unsigned integer
 =head2 Modifiers
 
 The following types modify the meaning of the prefix. 
-These are precede the prefixes:
+These are preceded by the prefixes:
 
 =over 5
 
@@ -350,7 +385,7 @@ user built array.
 
 =item C<c>
 
-const. Note that the proper order C<Type const> i.s.o. C<const Type>
+const. Note that the proper order is C<Type const> i.s.o. C<const Type>
 
 =item C<C>
 
@@ -374,6 +409,16 @@ reference
 
 =over 5
 
+=head2 Adjective
+
+Adjectives such as global and static should be spelled out in full.
+They come before the noun that they refer to, just as in normal english.
+
+foo_global_i: a global variable of type int commonly called "foo".
+
+static class members do not need the static_ prefix in the name (the
+Class::var notation usually makes it clear that it is static)
+
 =item C<loop_i>
 
 Variable loop: an integer
@@ -406,6 +451,18 @@ Variable bar: an C<Int*> that you must not delete
 
 Generally default arguments are taboo, except for nil pointers.
 
+The naming convention can be quite conveniently memorised, by
+expressing the type in english, and abbreviating it
+
+       static Array<int*> foo
+
+C<foo> can be described as "the static int-pointer user-array", so you get
+
+       foo_static_l_arr
+       
+
+
+
 =head1 MISCELLANEOUS
 
 For some tasks, some scripts are supplied, notably creating patches, a