partial: 1.0.1.jcn

[lilypond.git] / Documentation / CodingStyle.pod

diff --git a/Documentation/CodingStyle.pod b/Documentation/CodingStyle.pod
index db238815e64678c27eb31fc3373fe2f8b5b7f8bd..0f57d3e1b31bd48a60b019cf6bd519bad4a50105 100644 (file)
--- a/Documentation/CodingStyle.pod
+++ b/Documentation/CodingStyle.pod
@@ -4,7 +4,9 @@ CodingStyle - standards while programming for GNU LilyPond
 
 =head1 DESCRIPTION
 
-We 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")
                     )
                  )
 
@@ -179,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
 
@@ -283,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,
@@ -382,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
@@ -414,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