Coding practices

[address@hidden]

Hey all,

After reading over David's most recent e-mails to the list, it is clear to me 
that there is a coding-practice debt in LilyPond.  Standards of how and when to 
do certain things are not shared across all programmers, and things that seem 
commonsensical for some do not seem so for others.

Rather than letting this continue to be problematic, I'd like to establish a 
sort of GLISS for LilyPond coding style.  We would discuss certain conventions 
in the codebase to see where commonalities lie in the codebase and where things 
could be made to look more similar.  Absent of having the experience of someone 
like Han-Wen, Jann, or David, this will help amateur programmers like myself 
approach the task of contributing to LilyPond better.

I would like to organize the discussion along a few themes that, from my 
experience, seem important.  Comments for changes are welcome.  I'll more or 
less do what Graham did with GLISS - get comments from people and then do a 
sort of writeup.

1)      Class member functions versus non-member functions: when and why.
2)      LY_DEFINE versus MAKE_SCHEME_CALLBACK versus 
MAKE_DOCUMENTED_SCHEME_CALLBACK: when and why.
3)      Harmonization of variable names performing similar tasks.
4)      Function flow - standardizing the flow of functions that perform common 
tasks (returning offsets, grob arrays, etc.).
5)      Conventions for the writing of docstrings.
6)      Conventions for the writing of comments.
7)      Documentation of internal coding standards - how should this be done.
8)      Enforcing of internal coding standards via the build process - how 
should this be done.

For me, personally, I will not be able to continue on LilyPond work after the 
summer unless something like this is put in place.  I feel it is quite 
important and I hope that others agree to participate in this.

Cheers,
MS