release: 0.0.76

[lilypond.git] / Documentation / CodingStyle.pod

diff --git a/Documentation/CodingStyle.pod b/Documentation/CodingStyle.pod
index c1a9c7aed0981db668ecd76276027c59b2f65aba..8cf64c424dff1a6ab94f9943a8a386a1da20168a 100644 (file)
--- a/Documentation/CodingStyle.pod
+++ b/Documentation/CodingStyle.pod
@@ -1,10 +1,10 @@
 =head1 NAME
 
-CodingStyle - standards while programming for LilyPond
+CodingStyle - standards while programming for GNU LilyPond
 
 =head1 DESCRIPTION
 
-Please use these standards while doing programming for LilyPond
+Please use these standards while doing programming for GNU LilyPond
 
 Functions and methods do not return errorcodes, but use assert for
 checking status. 
@@ -12,7 +12,7 @@ checking status.
 =head2 Quote:
 
 A program should be light and agile, its subroutines
-connected like a strings of pearls.  The spirit and intent of
+connected like a string of pearls.  The spirit and intent of
 the program should be retained throughout.  There should be
 neither too little nor too much, neither needless loops nor
 useless variables, neither lack of structure nor overwhelming
@@ -38,12 +38,27 @@ this is to rewrite the program.
 Definitions of classes that are only accessed via pointers
 (*) or references (&) shall not be included as include files.
 
-Include files in C++ always have the file name extension ".hh".
+filenames
 
-Implementation files in C++ always have the file name
-extension ".cc".
+       ".hh"   Include files
+       ".cc"   Implementation files
+       ".icc"  Inline definition files
+       ".tcc"  non inline Template defs
+
+in emacs:
+
+       (setq auto-mode-alist
+             (append '(("\\.make$" . makefile-mode)
+                       ("\\.cc$" . c++-mode)
+                       ("\\.icc$" . c++-mode)
+                       ("\\.tcc$" . c++-mode)
+                       ("\\.hh$" . c++-mode)
+                       ("\\.pod$" . text-mode)         
+                       )
+                     auto-mode-alist))
 
-Inline definition files always have the file name extension ".icc".
+
+The class Class_name_abbreviation is coded in F<class-name-abbr.*>
 
 
 =head2 INDENTATION
@@ -60,6 +75,15 @@ in emacs:
                     )
                  )
 
+If you like using font-lock, you can also add this to your F<.emacs>:
+
+       (setq font-lock-maximum-decoration t)
+       (setq c++-font-lock-keywords-3 
+             (append
+              c++-font-lock-keywords-3
+              '(("\\b\\([a-zA-Z_]+_\\)\\b" 1 font-lock-variable-name-face)
+              ("\\b\\([A-Z]+[a-z_]+\\)\\b" 1 font-lock-type-face))
+              ))
 
 =head2 CLASSES and TYPES:
 
@@ -74,6 +98,12 @@ in emacs:
 the C<type> is a Hungarian notation postfix for C<Type>. See below
 
 
+=head2 BROKEN CODE
+
+Broken code (hardwired dependencies, hardwired constants, slow
+algorithms and obvious limitations) should be marked as such:
+either with a verbose TODO, or with a short "ugh" comment.
+
 =head2 COMMENTS
 
 The source is commented in the DOC++ style.  Check out doc++ at
@@ -81,6 +111,7 @@ http://www.zib.de/Visual/software/doc++/index.html
 
        /*
                C style comments for multiline comments.
+               They come before the thing to document.
                [...]
        */
 
@@ -89,6 +120,8 @@ http://www.zib.de/Visual/software/doc++/index.html
                short description.
                Long class documentation.
                (Hungarian postfix)
+
+               TODO Fix boring_member()
        */
        class Class {
                /**
@@ -107,22 +140,14 @@ http://www.zib.de/Visual/software/doc++/index.html
                Rettype member(Argtype);
 
                /// memo only
-               boring_member();
+               boring_member() {
+                       data_member_ = 121; // ugh
+               }
        };
 
-Unfortunately most of the code isn't really documented that good.
-
-
-=head2 CLASSNAMES (2)
-
-A lot of classes in LilyPond start with 'P', this is to distinguish
-certain parts of LilyPond: the P stands for Printer, and the P-classes
-are supposed to be more lowlevel than the others. Example:
 
-Staff uses PStaff, PScore and PCol to do the typesetting of
-symbols. Staff is  the "brains" for PStaff
-
-NB: in PCursor (which is part of the library) P stands for PointerCursor
+       
+Unfortunately most of the code isn't really documented that good.
 
 
 =head2 MEMBERS (2)
@@ -219,8 +244,7 @@ not very useful if not used consistently
 
 =item *
 
-usefullness in I<very large> 
-(but how many classes is very large?)
+usefullness in I<very large> (but how many classes is very large?)
 remains an issue.
 
 =back
@@ -247,6 +271,7 @@ use no, or pick less silly, abbrvs.
 =item *
 
 use non-ambiguous postfixes C<identifier_name_type_modifier[_modifier]>
+
 =back
 
 Macros, C<enum>s and C<const>s are all uppercase,
@@ -377,3 +402,23 @@ Variable bar: an C<Int*> that you must not delete
 =back
 
 Generally default arguments are taboo, except for nil pointers.
+
+=head1 MISCELLANEOUS
+
+For some tasks, some scripts are supplied, notably creating patches, a
+mirror of the website, generating the header to put over cc and hh
+files, doing a release.
+
+Use them.
+
+The following generic identifications are used:
+
+       up == 1
+       left == -1
+       right == 1
+       down == -1
+
+Intervals are pictured lying on a horizontal numberline (Interval[-1]
+is the minimum). The 2D plane has +x on the right, +y pointing up.
+
+