CodingStyle - standards while programming for GNU LilyPond

Han-Wen Nienhuys and Jan Nieuwenhuizen



Table of Contents



()

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.

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"

LANGUAGES

C++, /bin/sh and Python are preferred. Perl is not. Python code should use an indent of 8, using TAB characters.

FILES

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

filenames


	".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))

The class Class_name_abbreviation is coded in class-name-abbr.*

INDENTATION

in emacs:


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

If you like using font-lock, you can also add this to your .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))
	       ))

CLASSES and TYPES:


	This_is_a_class

MEMBERS


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

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

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 DECLARE_VIRTUAL_FUNCTIONS ().

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.

COMMENTS

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


	/*
		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.

MEMBERS (2)

Standard methods:


	///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 (..)

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

HUNGARIAN NOTATION NAMING CONVENTION

Proposed is a naming convention derived from the so-called Hungarian Notation. Macros, enums and consts are all uppercase, with the parts of the names separated by underscores.

Types

byte
unsigned char. (The postfix _by is ambiguous)

b
bool

bi
bit

ch
char

f
float

i
signed integer

str
string class

sz
Zero terminated c string

u
unsigned integer

User defined types


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

Modifiers

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

a
array

array
user built array.

c
const. Note that the proper order is Type const i.s.o. const Type

C
A const pointer. This would be equivalent to _c_l, but since any "const" pointer has to be a link (you can't delete a const pointer), it is superfluous.

l
temporary pointer to object (link)

p
pointer to newed object

r
reference

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)

loop_i
Variable loop: an integer

u
Temporary variable: an unsigned integer

test_ch
Variable test: a character

first_name_str
Variable first_name: a String class object

last_name_ch_a
Variable last_name: a char array

foo_i_p
Variable foo: an Int* that you must delete

bar_i_l
Variable bar: an 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

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


	foo_static_l_arr

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.


Return to GNU LilyPond's home page.

Please send GNU LilyPond questions and comments to gnu-music-discuss@gnu.org.

Please send comments on these web pages to (address unknown), send other FSF & GNU inquiries and questions to gnu@gnu.org.

Copyright (c) 1997, 1998, 1999 Han-Wen Nienhuys and Jan Nieuwenhuizen.

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.


This page was built from GNU LilyPond-1.1.57 by

root <(address unknown)>, at Tue Jul 13 11:30:22 1999 CDT.