release: 1.0.2

[lilypond.git] / Documentation / CodingStyle.yo

report(CodingStyle - standards while programming for GNU
LilyPond)(Han-Wen Nienhuys and Jan Nieuwenhuizen)()()

nsect(DESCRIPTION)

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.

quote(

A program should be light and agile, its subroutines
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
rigidity.

A program should follow the 'Law of Least
Astonishment'.  What is this law?  It is simply that the
program should always respond to the user in the way that
astonishes him least.

A program, no matter how complex, should act as a
single unit.  The program should be directed by the logic
within rather than by outward appearances.

If the program fails in these requirements, it will be
in a state of disorder and confusion.  The only way to correct
this is to rewrite the program.

-- Geoffrey James, "The Tao of Programming"
)


nsubsect(LANGUAGES)

C++, /bin/sh and python are preferred.  Perl is not.

nsubsect(FILES)

Definitions of classes that are only accessed via pointers
(*) or references (&) shall not be included as include files.

filenames

verb(
        ".hh"   Include files
        ".cc"   Implementation files
        ".icc"  Inline definition files
        ".tcc"  non inline Template defs
)

in emacs:

verb(
        (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))
)


The class Class_name_abbreviation is coded in file(class-name-abbr.*)


nsubsect(INDENTATION)

in emacs:

verb(
        (add-hook 'c++-mode-hook
                  '(lambda() (c-set-style "gnu")
                     )
                  )
)

If you like using font-lock, you can also add this to your file(.emacs):

verb(
        (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))
               ))
)

nsubsect(CLASSES and TYPES:)

verb(
        This_is_a_class
        AClass_name     (for Abbreviation_class_name)
)

nsubsect(MEMBERS)

verb(
        Class::member()
        Type Class::member_type_
        Type Class::member_type()
)

the code(type) is a Hungarian notation postfix for code(Type). See below

nsubsect(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, because we had a macro that looked like
code(DECLARE_VIRTUAL_FUNCTIONS()). 

nsubsect(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.

nsubsect(COMMENTS)

The source is commented in the DOC++ style.  Check out doc++ at
lurl(http://www.zib.de/Visual/software/doc++/index.html)

verb(
        /*
                C style comments for multiline comments.
                They come before the thing to document.
                [...]
        */


        /**
                short description.
                Long class documentation.
                (Hungarian postfix)

                TODO Fix boring_member()
        */
        class Class {
                /**
                  short description.
                  long description
                */

                Data data_member_;


                /**
                        short memo. long doco of member()
                        @param description of arguments
                        @return Rettype
                */
                Rettype member(Argtype);

                /// memo only
                boring_member() {
                        data_member_ = 121; // ugh
                }
        };
)

        
Unfortunately most of the code isn't really documented that good.


nsubsect(MEMBERS (2))

Standard methods:

verb(
        ///check that *this satisfies its invariants, abort if not.
        void OK() const

        /// print *this (and substructures) to debugging log
        void print() const

        /**
        protected member. Usually invoked by non-virtual XXXX()
        */
        virtual do_XXXX()

        /**add some data to *this.
        Presence of these methods usually imply that it is not feasible to this
        via  a constructor
        */
        add (..)

        /// replace some data of *this
        set (..)
)

nsubsect(Constructor)

Every class should have a default constructor.  

Don't use non-default constructors if this can be avoided:

verb(
        Foo f(1)
)

is less readable than

verb(
        Foo f;
        f.x = 1
)

or 

verb(
        Foo f(Foo_convert::int_to_foo (1))
)

nsect(HUNGARIAN NOTATION NAMING CONVENTION)

Proposed is a naming convention derived from the so-called
em(Hungarian Notation).

nsubsect(Hungarian)

The Hungarian Notation was conceived by or at least got its name from,
the hungarian programmer Charles Simonyi.  It is a naming convention 
with the aim to make code more readable (for fellow programmers), and 
more accessible for programmers that are new to a project.

The essence of the Hungarian Notation is that every identifier has a
part which identifies its type (for functions this is the result
type).  This is particularly useful in object oriented programming,
where a particular object implies a specific interface (a set of
member functions, perhaps some redefined operators), and for
accounting heap allocated memory pointers and links.

nsubsect(Advantages)

Another fun quote from Microsoft Secrets:

quote(
        The Hungarian naming convention gives developers the ability
        to read other people's code relatively easily, with a minmum
        number of comments in the source code.  Jon De Vann estimated
        that only about 1 percent of all lines in the Excel product
        code consist of comments, but the code is still very
        understandable due to the use of Hungarian: "if you look at
        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!  (Didn't MMM-Brooks say `There is
no silver bullet?' --HWN)


nsubsect(Disadvantages)

itemize(
it()more keystrokes (disk space!)
it()it looks silly code(get_slu_p())
it()it looks like code from micro suckers
it()(which) might scare away some (otherwise good?)
    progammers, or make you a paria in the free
    software community
it()it has ambiguities
it()not very useful if not used consistently
it()usefullness in em(very large) (but how many classes is very large?)
    remains an issue.
)

nsubsect(Proposal)

itemize(
it()learn about cut and paste / use emacs or vi
    or lean to type using ten fingers
it()Use emacs dabbrev-expand, with dabbrev-case-fold-search set to nil.
it()use no, or pick less silly, abbrvs.
it()use non-ambiguous postfixes code(identifier_name_type_modifier[_modifier])
it()There is no need for Hungarian if the scope of the variable is small,
    ie. local variables, arguments in function definitions (not
    declarations).
)

Macros, code(enum)s and code(const)s are all uppercase,
with the parts of the names separated by underscores.

nsubsect(Types)

description(
dit(code(byte))
    unsigned char. (The postfix _by is ambiguous)
dit(code(b))
    bool
dit(code(bi))
    bit
dit(code(ch))
    char
dit(code(f))
    float
dit(code(i))
    signed integer
dit(code(str))
    string class
dit(code(sz))
    Zero terminated c string
dit(code(u))
    unsigned integer
)

nsubsect(User defined types)

verb(
        /** Slur blah. blah.
        (slur)
        */
        class Slur {};
        Slur* slur_p = new Slur;
)

nsubsect(Modifiers)

The following types modify the meaning of the prefix. 
These are preceded by the prefixes:

description(
dit(code(a))
    array
dit(code(array))
    user built array.
dit(code(c))
    const. Note that the proper order is code(Type const)
    i.s.o. code(const Type)
dit(code(C))
    A const pointer. This would be equivalent to code(_c_l), but since any
    "const" pointer has to be a link (you can't delete a const pointer),
    it is superfluous.
dit(code(l))
    temporary pointer to object (link)
dit(code(p))
    pointer to newed object
dit(code(r))
    reference
)

nsubsect(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.

verb(
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)

description(
dit(code(loop_i))
    Variable loop: an integer
dit(code(u))
    Temporary variable: an unsigned integer
dit(code(test_ch))
    Variable test: a character
dit(code(first_name_str))
    Variable first_name: a String class object
dit(code(last_name_ch_a))
    Variable last_name: a code(char) array
dit(code(foo_i_p))
    Variable foo: an code(Int*) that you must delete
dit(code(bar_i_l))
    Variable bar: an code(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

verb(
        static Array<int*> foo
)

code(foo) can be described as "the static int-pointer user-array", so you get

verb(
        foo_static_l_arr
)



nsect(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:

verb(
        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.