Coding style

[uliska]

What do we do about coding style conventions?

While it seems overly complex to agree upon coding styles for such a small project, this is in general of course very useful.

While not wanting to interfere too much, there are a few things that should be defined especially in the context of git collaboration: Basic requirement is to have as much as possible in single code lines (for the versioning to work smoothly). I think this is also a good coding convention in general. So I suggest the following conventions:

• Each measure starts on a new line with no extra indent
• Each measure should be preceded by a one line comment with the measure number (I find it extremely problematic reading sources by others which don't contain enough measure numbers)
• If it is necessary to deviate from the one-measure-one-line rule (e.g. with polyphonic or tuplet constructs that span more than one measure) all following lines should be indented by at least four spaces. If possible insert one line measure number comments anyway.
• barNumberChecks should also be in a single line (maybe with a zero indent to make them stand out)
• complex tweaks (e.g. function calls with parameters) should be placed in single lines. This means: start the measure on a new line, insert a newline and additional indentation, write the tweak, add a newline and continue the measure with the extra indentation.

This is a set of general coding rules that doesn't interfere with concrete coding preferences. What do you think? Of course in bigger projects it would be useful to add further specifications

[colinghall]

It is a very good idea to establish some rules for this. The idea is that we all work on each other's code without ending up tweaking layout. It also helps to keep a clean revision history because all the edits relate to functional changes.

But we should not have to invent them as there is already an example; the Lilypond project itself.

Are there lilypond coding standards documented in the Lilypond project. I would ask but it would be a great way to start another online debate!

Better still would be a canonical formatter (like astyle) for Lilypond. Your last task before commiting is to run the source through a formatter and then it is forced to be in the correct layout. Any diffs are due to real changes in the source.

Cheers, Colin.

[colinghall]

If you run git log --pretty=one-line you can see the effect of long leading lines in the commit messages.

Check out the Lilypond git log for an example of good use.

See http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

[colinghall]

Sorry, that's not really on the topic of coding conventions.

It's actually just good standard git practice, not Lilypond specific.

We should identify a source for good practice in git and refer to it. Any deviations we record in our practice documentation

[uliska]

It is a very good idea to establish some rules for this. The idea is that we all work on each other's code without ending up tweaking layout. It also helps to keep a clean revision history because all the edits relate to functional changes.

But we should not have to invent them as there is already an example; the Lilypond project itself. That's a good idea.

Are there lilypond coding standards documented in the Lilypond project. I would ask but it would be a great way to start another online debate! I don't have any idea. Maybe Janek is more into this ...

Better still would be a canonical formatter (like astyle) for Lilypond. Your last task before commiting is to run the source through a formatter and then it is forced to be in the correct layout. Any diffs are due to real changes in the source. This is completely new to me. Is there such a thing as a code formatter for LilyPond? And: What aspects would this touch? There are so many things you can write differently:

     c4~ vs. c4 ~
     c4 [ ( \startTextSpan \f \> d ) ] vs c4[(\f\>\startTextSpan d])

To name just a few things.

But my point was specific to our interest to have as many entities as 
possible in single lines. And I don't know if this complies with 
established standards.
Best
Urs
>
> Cheers,
> Colin.
>
> ---
> Reply to this email directly or view it on GitHub:
> https://github.com/uliska/collaborative-lilypond-editing/issues/9#issuecomment-6165004

-- 
Urs Liska |
Glümerstr. 5 |
D-79102 Freiburg |
Tel. +49(0)761-5903213 |
Fax. +49(0)761-38436816 |
Mob. +49(0)179-4642905 |
mail@ursliska.de |
http://www.ursliska.de

[uliska]

If you run git log --pretty=one-line you can see the effect of long leading lines in the commit messages.

Check out the Lilypond git log for an example of good use.

See http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html Thank you, I really didn't know that!

[colinghall]

On Wed, Jun 06, 2012 at 04:15:23PM -0700, uliska wrote:

If you run git log --pretty=one-line you can see the effect of long leading lines in the commit messages.

Check out the Lilypond git log for an example of good use.

See http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html Thank you, I really didn't know that!

---

Reply to this email directly or view it on GitHub: https://github.com/uliska/collaborative-lilypond-editing/issues/9#issuecomment-6165313

You're welcome!

Much of what we are doing is standard practice in the software development world.

Cheers, Colin.

Colin Hall

[uliska]

... and what I currently am interested in is make these standard practices fruitful in music editing world. I hope to be able to use a few contacts to launch a few reference projects that could be noticed quite well in (German) musicology. So I'm eager to learn... I know much about programming and have considerable experience - but this in no way professional. So I think I will be able to understand everything quickly, but I'm surely missing most of what on acquires through real IT education.

[uliska]

Considering this discussion: http://lists.gnu.org/archive/html/lilypond-user/2012-06/msg00176.html I'd say the following:

• Currently there is no code formatter readily available, so we have to deal without it
• At least for this project we don't invent a full-blown coding style rule set.
• But we can at least adhere to three rules
  • Place as many items in individual lines
  • Enter measure number comments for every measure in a separate line before the music
  • Do not change any existing music definitions for styling reasons. Only change anything in an exisiting line of code if you have to change the musical content. (This is to prevent the diff to detect false differences)

If we agree upon this I'll add it to the readme file

[colinghall]

On Fri, Jun 08, 2012 at 01:22:55AM -0700, uliska wrote:

• Currently there is no code formatter readily available, so we have to deal without it

Yes.

• At least for this project we don't invent a full-blown coding style rule set.

Agreed

• But we can at least adhere to three rules Place as many items in individual lines

Yes.

• Enter measure number comments for every measure in a separate line before the music

I'll go with this for this project.

If we're in the process of developing general rules then I think there are situation where this rule does not make sense.

Why? Two reasons. I arrange jazz charts and there is often a lot of re-use between sections, so a particular piece of Lilypond source usually appears more than once in the finished parts and score. Sometimes fragments appear multiple times within a section e.g. James Brown type horn riffs.

The other reason is that not all parts have the same repeat structure. So for some parts there are 200 bars, but for others perhaps 70 to 100 bars.

• Do not change any existing music definitions for styling reasons. Only change anything in an exisiting line of code if you have to change the musical content. (This is to prevent the diff to detect false differences)

Agreed. Usually this happens unintentionally. A good way to catch it is to perform a diff before you "git add" and confirm that the diffs are only in the parts you deliberately changed.

If we agree upon this I'll add it to the readme file

Fine with me.

Cheers, Colin.

Colin Hall

[uliska]

• Enter measure number comments for every measure in a separate line before the music I'll go with this for this project.

If we're in the process of developing general rules then I think there are situation where this rule does not make sense.

Why? Two reasons. I arrange jazz charts and there is often a lot of re-use between sections, so a particular piece of Lilypond source usually appears more than once in the finished parts and score. Sometimes fragments appear multiple times within a section e.g. James Brown type horn riffs.

The other reason is that not all parts have the same repeat structure. So for some parts there are 200 bars, but for others perhaps 70 to 100 bars.

OK, I didn't think of this of course. I have also run into this situation sometimes, but from what I generally do this was the exception to the rule, so I just didn't take it seriously.

But I think the basic idea of the rule is still valid and only has to be modified: If I read someone else's code (and this includes my own if it is older than 48 hours ...) it reduces the time needed to navigate the source by magnitudes if every line of code is commented. And if you have a structure where simple measure numbering doesn't fit you can still say: "place a one line comment before any music indicating its measure number or its usage" Personally I'd in such a case put a) a verbal description and b) the measure number of the first appearance in the score in it. What do you think (well, in general, not for this project)?

• Do not change any existing music definitions for styling reasons. Only change anything in an exisiting line of code if you have to change the musical content. (This is to prevent the diff to detect false differences) Agreed. Usually this happens unintentionally. A good way to catch it is to perform a diff before you "git add" and confirm that the diffs are only in the parts you deliberately changed.

Good point.

Best Urs

[colinghall]

On Fri, Jun 08, 2012 at 02:11:58AM -0700, uliska wrote:

• Enter measure number comments for every measure in a separate line before the music I'll go with this for this project.

But I think the basic idea of the rule is still valid and only has to be modified: If I read someone else's code (and this includes my own if it is older than 48 hours ...) it reduces the time needed to navigate the source by magnitudes if every line of code is commented. And if you have a structure where simple measure numbering doesn't fit you can still say: "place a one line comment before any music indicating its measure number or its usage"

Yes, this is good.

Personally I'd in such a case put a) a verbal description and b) the measure number of the first appearance in the score in it. What do you think (well, in general, not for this project)?

I like your suggestion.

Cheers, Colin.

Colin Hall

[jan-warchol]

On Wed, Jun 6, 2012 at 10:56 AM, uliska reply@reply.github.com wrote:

What do we do about coding style conventions?

While it seems overly complex to agree upon coding styles for such a small project, this is in general of course very useful.

While not wanting to interfere too much, there are a few things that should be defined especially in the context of git collaboration: Basic requirement is to have as much as possible in single code lines (for the versioning to work smoothly). I think this is also a good coding convention in general. So I suggest the following conventions:

• Each measure starts on a new line with no extra indent

+1

• Each measure should be preceded by a one line comment with the measure number

-1, at least for this project. I find them very tedious to type; this should be added by some sort of automatic formatter.

(I find it extremely problematic reading sources by others which don't contain enough measure numbers)

What about Frescobaldi's two-way point-and-click? For me this feature is more than enough to edit anything i want.

• If it is necessary to deviate from the one-measure-one-line rule (e.g. with polyphonic or tuplet constructs that span more than one measure) all following lines should be indented

i was thinking about standarizing this for some time. This may be good approach.

by at least four spaces.

Not sure about this. I find Frescobaldi's default 2-space indent quite good.

If possible insert one line measure number comments anyway.

i suggest to have them unindented to show where measure begins:

\time 4/4 |%m.1 r8 e e e f16\melisma g f e f g e f |%m.2 g a g f g a f g a8 bes16 a g f e d

• barNumberChecks should also be in a single line (maybe with a zero indent to make them stand out)

-1 for zero indent.

What do you think?

Too complicated to maintain by hand :P But it would be great to extend Frescobaldi's formatting options to include these things.

best, Janek

[jan-warchol]

Wow, i missed a lot of discussion! In addition to what i've sent above:

• i agree with most of your conclusions
• there is a need for a standarized code formatting style indeed
• an "astyle for Lily" should be created and used automatically in Frescobaldi and similar programs.

[uliska]

Am 08.06.2012 16:02, schrieb Janek Warchoł:

Wow, i missed a lot of discussion! In addition to what i've sent above:

• i agree with most of your conclusions :-)
• there is a need for a standarized code formatting style indeed Yes, but we'll only scratch the surface in this project, I think. Maybe openLilyLib will be a place to discuss this further.
• an "astyle for Lily" should be created and used automatically in Frescobaldi and similar programs. +1 Separate project... Doesn't have directly be included into lilypond development.

---

Reply to this email directly or view it on GitHub: https://github.com/uliska/collaborative-lilypond-editing/issues/9#issuecomment-6203456

[uliska]

• Each measure should be preceded by a one line comment with the measure number -1, at least for this project. I find them very tedious to type; this should be added by some sort of automatic formatter. Can an algorithm on source code level (i.e. without running lilypond) reliably determine measure numbers? And what about Colin's comments about non-linear music sources? But I'd agree that we can leave them out in this project, as we have only a few measures anyway ... (I find it extremely problematic reading sources by others which don't contain enough measure numbers) What about Frescobaldi's two-way point-and-click? For me this feature is more than enough to edit anything i want. No. The (at least one) point in LilyPond's text input is having a timeless, human readable format that isn't dependent on specific applications. Relying on specific abilities of a specific software tool in a specific version (I couldn not install Frescobaldi 2 so far, for example) would seriously compromise this. Readability has to be provided on source level.
• If it is necessary to deviate from the one-measure-one-line rule (e.g. with polyphonic or tuplet constructs that span more than one measure) all following lines should be indented i was thinking about standarizing this for some time. This may be good approach. I will write a few examples when I'll update the readme. by at least four spaces. Not sure about this. I find Frescobaldi's default 2-space indent quite good. Hm. Have no real opinion on this. But I find the 2-space indent somewhat hard to perceive when returning to a certain indentation level 20 lines later. If possible insert one line measure number comments anyway. i suggest to have them unindented to show where measure begins:

\time 4/4 |%m.1 r8 e e e f16\melisma g f e f g e f |%m.2 g a g f g a f g a8 bes16 a g f e d This is nice. But apart from what I was talking about. What I wanted to say is: Please enter measure numbers for every voice in a polyphonic section that goes over measure boundaries. I'll give examples for this also.

• barNumberChecks should also be in a single line (maybe with a zero indent to make them stand out) -1 for zero indent. OK. Why?

What do you think? Too complicated to maintain by hand :P But it would be great to extend Frescobaldi's formatting options to include these things. Yes. Separate project, as said in other comment ;-) Best Urs

[jan-warchol]

On Fri, Jun 8, 2012 at 4:13 PM, uliska

• Each measure should be preceded by a one line comment with the measure number -1, at least for this project.  I find them very tedious to type; this should be added by some sort of automatic formatter.

Can an algorithm on source code level (i.e. without running lilypond) reliably determine measure numbers?

Probably. IIRC LilyPondTool checked barchecks on its own - i.e. it calculated all durations etc. without running Lily.

And what about Colin's comments about non-linear music sources?

This one will be hard.

The (at least one) point in LilyPond's text input is having a timeless, human readable format that isn't dependent on specific applications. Relying on specific abilities of a specific software tool in a specific version (I couldn not install Frescobaldi 2 so far, for example) would seriously compromise this. Readability has to be provided on source level.

i agree - it's just that i'm lazy :)

• barNumberChecks should also be in a single line (maybe with a zero indent to make them stand out) -1 for zero indent. OK. Why?
• if the code isn't indented, zero indent would mean nothing
• gets messy when indentation level changes: copy a fragment that has 1st level indent (with some 0-indented barchecks) to 3rd indentation level code and everything goes wrong
• it's against the logic of "indent = structure level"

[uliska]

Can an algorithm on source code level (i.e. without running lilypond) reliably determine measure numbers? Probably. IIRC LilyPondTool checked barchecks on its own - i.e. it calculated all durations etc. without running Lily.

And what about Colin's comments about non-linear music sources? This one will be hard. If music is repeated or used in several places ( a variable could even be referenced from a section with a different time signature) there will be no way to automatically create sensible comments. I would also feel this is too strict - somehow formatting would interfere too much with content IMHO. A source formatter could try offering this as an additional option, but one that has to be activated, not one that has to be deactivated.

• barNumberChecks should also be in a single line (maybe with a zero indent to make them stand out)

  -1 for zero indent. OK. Why?

• if the code isn't indented, zero indent would mean nothing
• gets messy when indentation level changes: copy a fragment that has 1st level indent (with some 0-indented barchecks) to 3rd indentation level code and everything goes wrong
• it's against the logic of "indent = structure level" OK.

I think thinking about a source formatter would be a good idea. And it could well complement a lilyDoc project (which I'm also finding very important - think about how easy you get lost in our library).