headers
Graham Percival | 9 Aug 2012 11:01
Picon
Favicon

GOP2-4 - C++ and scheme indentation

http://lilypond.org/~graham/gop/gop_5.html

** Proposal summary

Speaking academically, scheme code style is a “solved problem”.
Let’s pick one of the existing solutions, and let a computer deal
with this. Humans should not waste their time, energy, and
creativity manually adding tabs or spaces to source code.

C++ will remain as-is, using astyle 2.02 (not astyle2.02.1) with
scripts/auxiliar/fix-scheme.sh

Scheme will be indented with a yet-to-be written
scripts/auxiliar/fix-scheme.sh, which does the same thing as
emacs.

** Motivation

New contributors sometimes struggle to follow our indentation and
code style – this is especially difficult when parts of our
existing source code doesn’t have a consistent style. This is
problematic... we want new contributors to be struggling with the
lilypond architecture, not playing games in their text editors!

We discussed this last year, but it didn’t quite turn into a
patch. This led to yet another round of disheartening confusion
for a well-intentioned new contributor, i.e.
 	
http://codereview.appspot.com/5343050/#msg5
http://codereview.appspot.com/5320074
(Continue reading)

Permalink | Reply |
headers
Jan Nieuwenhuizen | 9 Aug 2012 12:21
Picon
Gravatar

Re: GOP2-4 - C++ and scheme indentation

Graham Percival writes:

> ** Motivation
>
> New contributors sometimes struggle to follow our indentation and
> code style

Yes, that's bad.  Do we explain that we're a GNU project and as
such use GNU coding style?  Together with a pointer to the info
node *(standards)Formatting, that could help.

> – this is especially difficult when parts of our
> existing source code doesn’t have a consistent style.

Yes, and even more so if we don't explain what the style is?

What could help, though, is to just accept small patches that have
formatting problems, run C-x h C-M-\ , tell them thank you and show
them the reformatted diff from C-x v = ?

This is where Rietveld, git-cl, policy and possibly the benevolent
dictator comes in?

Greetings,
Jan

--

-- 
Jan Nieuwenhuizen <janneke <at> gnu.org> | GNU LilyPond http://lilypond.org
Freelance IT http://JoyofSource.com | Avatar®  http://AvatarAcademy.nl
(Continue reading)

Permalink | Reply |
headers
Graham Percival | 9 Aug 2012 12:36
Picon
Favicon

Re: GOP2-4 - C++ and scheme indentation

On Thu, Aug 09, 2012 at 12:21:06PM +0200, Jan Nieuwenhuizen wrote:
> Graham Percival writes:
> 
> > New contributors sometimes struggle to follow our indentation and
> > code style
> 
> Yes, that's bad.  Do we explain that we're a GNU project and as
> such use GNU coding style?  Together with a pointer to the info
> node *(standards)Formatting, that could help.

Given that I don't think that we follow GNU style exactly, I don't
think that's relevant.

> > – this is especially difficult when parts of our
> > existing source code doesn’t have a consistent style.
> 
> Yes, and even more so if we don't explain what the style is?
> 
> What could help, though, is to just accept small patches that have
> formatting problems, run C-x h C-M-\ , tell them thank you and show
> them the reformatted diff from C-x v = ?

You didn't read carefully enough:
>> Emacs is not an answer; nobody wants to install 50 megabytes
>> just to format scheme code. Especially when a standalone tool
>> could do the job in probably less than 10 Kb.

I do not have emacs installed.  I *WILL NOT* have Emacs installed.
Carl has gone on record as saying that he will not use Emacs.
IIRC Reinhold has also gone on record.  We could conduct a poll if
(Continue reading)

Permalink | Reply |
headers
David Kastrup | 9 Aug 2012 13:08
X-Face
Picon
Picon

Re: GOP2-4 - C++ and scheme indentation

Graham Percival <graham <at> percival-music.ca> writes:

> I do not have emacs installed.  I *WILL NOT* have Emacs installed.
> Carl has gone on record as saying that he will not use Emacs.
> IIRC Reinhold has also gone on record.  We could conduct a poll if
> you want to see other people who do not, and *WILL NOT*, install
> emacs just to format scheme code.
>
> Do you want to tell me (and them) that we shouldn't be editing
> .scm files in lilypond?

Scheme is a programming language which is close to impossible to
understand without consistent indentation, and to indent consistently
without support of a Scheme-aware editor.

This is not satisfactorily solved by first writing everything and
running an indenter afterwards.  You'll mess up the nesting levels and
your program will not work.

It does not matter whether your Scheme-aware editor is called Emacs.
Emacs has the advantage of also being LilyPond-aware, and being
Texinfo-aware, and C++-aware and navigating LilyPond documentation
including graphics about 10 times faster than any HTML browser.

Finding a good replacement for all those tasks is a challenge.

> I repeat: formatting source code is a computationally solved problem.

With LilyPond, not even _understanding_ source code is solved well.
(Continue reading)

Permalink | Reply |
headers
Graham Percival | 9 Aug 2012 13:23
Picon
Favicon

Re: GOP2-4 - C++ and scheme indentation

On Thu, Aug 09, 2012 at 01:08:42PM +0200, David Kastrup wrote:
> Graham Percival <graham <at> percival-music.ca> writes:
> 
> > Do you want to tell me (and them) that we shouldn't be editing
> > .scm files in lilypond?
> 
> This is not satisfactorily solved by first writing everything and
> running an indenter afterwards.  You'll mess up the nesting levels and
> your program will not work.

Yeah, but I find it way easier to write scheme code with matching
parentheses.  I wrote ly/event-listener.ly like this:

#(define (format-note engraver event)
   (let* ((origin (ly:input-file-line-char-column
                   (ly:event-property event 'origin)
                  )
         ))
     (print-line engraver
                 "note"
                 ;; get a MIDI pitch value.
                 (+ 60 (ly:pitch-semitones
                        (ly:event-property event 'pitch)
                       )
                 )
                 (ly:duration->string
                  (ly:event-property event 'duration))
                 (format-moment (ly:duration-length
                                 (ly:event-property event
'duration)
(Continue reading)

Permalink | Reply |
headers
David Kastrup | 9 Aug 2012 13:34
X-Face
Picon
Picon

Re: GOP2-4 - C++ and scheme indentation

Graham Percival <graham <at> percival-music.ca> writes:

> On Thu, Aug 09, 2012 at 01:08:42PM +0200, David Kastrup wrote:
>> 
>> The stumbling block is _writing_ the Scheme code, not submitting it.
>> When is the last time a code review complained about Scheme code
>> formatting?
>
> I gave URLs in the proposal, but here you go:
> http://codereview.appspot.com/5343050/#msg1
> http://codereview.appspot.com/5343050/#msg5
> (note that there were 3 or 4 different rietveld issues discussing
> that particular patchset, so previous discussion is not on that
> page)

The submitter _reformatted_ existing code with different conventions.
His own work was not put into question as far as I can see.

> That's not necessarily the last time, but it was within the past
> year, and it royally screwed over a new contributor.

I don't see that picking some rules will change the perspectives of
gratuitous changes significantly.

--

-- 
David Kastrup
Permalink | Reply |
headers
David Kastrup | 9 Aug 2012 13:41
Picon
Picon

Re: GOP2-4 - C++ and scheme indentation

Graham Percival <graham <at> percival-music.ca> writes:

> On Thu, Aug 09, 2012 at 01:08:42PM +0200, David Kastrup wrote:
>> Graham Percival <graham <at> percival-music.ca> writes:
>> 
>> > Do you want to tell me (and them) that we shouldn't be editing
>> > .scm files in lilypond?
>> 
>> This is not satisfactorily solved by first writing everything and
>> running an indenter afterwards.  You'll mess up the nesting levels and
>> your program will not work.
>
> Yeah, but I find it way easier to write scheme code with matching
> parentheses.  I wrote ly/event-listener.ly like this:
>
> #(define (format-note engraver event)
>    (let* ((origin (ly:input-file-line-char-column
>                    (ly:event-property event 'origin)
>                   )
>          ))

It is "way easier" because you are not using a Scheme-aware editor.  And
probably not the most Scheme-aware author...  Shrug.

It is not even unlikely that vim might have something to offer in that
area.  I am not really interested all that much in automatic
indentation, or fixed rules.  People should write Scheme recognizable as
Scheme, C++ recognizable as C++, LilyPond recognizable as LilyPond.
There are reasonably established conventions for that.  Usually applying
them with a grain of salt leads to better readability rather than
(Continue reading)

Permalink | Reply |
headers
Keith OHara | 10 Aug 2012 10:26

Re: GOP2-4 - C++ and scheme indentation

Graham Percival <graham <at> percival-music.ca> writes:

> On Thu, Aug 09, 2012 at 12:21:06PM +0200, Jan Nieuwenhuizen wrote:
>
> > Do we explain that we're a GNU project and as
> > such use GNU coding style?  Together with a pointer to the info
> > node *(standards)Formatting, that could help.
> 
> Given that I don't think that we follow GNU style exactly, I don't
> think that's relevant.

I think we *do* follow GNU style exactly in the C++ code.

Remember that the formatting guidelines in the GNU standard referenced
above are quite brief, and says: 
  We don’t think of these recommendations as requirements, because it 
  causes no problems for users if two different programs have different
  formatting styles. 
  But whatever style you use, please use it consistently, 

> > What could help, though, is to just accept small patches that have
> > formatting problems, run C-x h C-M-\ , tell them thank you and show
> > them the reformatted diff from C-x v = ?

But beware that this uses mixed tabs and spaces, unless you have
configured emacs to use spaces only, as most people prefer today,
... and that it left-justifies block comments, some of which are
not meant to be left-justified, ... and that you need extra 
parentheses to properly indent complex expressions.
(Continue reading)

Permalink | Reply |
headers
David Kastrup | 10 Aug 2012 10:45
X-Face
Picon
Picon

Re: GOP2-4 - C++ and scheme indentation

Keith OHara <k-ohara5a5a <at> oco.net> writes:

> But beware that this uses mixed tabs and spaces, unless you have
> configured emacs to use spaces only, as most people prefer today,

Should we put up directory-local variables to promote this and a few
other conventions?

    File: emacs.info,  Node: Directory Variables,  Prev: File Variables,  Up: Variables

    48.2.5 Per-Directory Local Variables
    ------------------------------------

    Sometimes, you may wish to define the same set of local variables to
    all the files in a certain directory and its subdirectories, such as
    the directory tree of a large software project.  This can be
    accomplished with "directory-local variables".

       The usual way to define directory-local variables is to put a file
    named `.dir-locals.el'(1) in a directory.  Whenever Emacs visits any
    file in that directory or any of its subdirectories, it will apply the
    directory-local variables specified in `.dir-locals.el', as though they
    had been defined as file-local variables for that file (*note File
    Variables::).  Emacs searches for `.dir-locals.el' starting in the
    directory of the visited file, and moving up the directory tree.  To
    avoid slowdown, this search is skipped for remote files.  If needed,
    the search can be extended for remote files by setting the variable
    `enable-remote-dir-locals' to `t'.

       The `.dir-locals.el' file should hold a specially-constructed list,
(Continue reading)

Permalink | Reply |
headers
Jan Nieuwenhuizen | 10 Aug 2012 12:28
Picon
Gravatar

Re: GOP2-4 - C++ and scheme indentation

David Kastrup writes:

> Keith OHara <k-ohara5a5a <at> oco.net> writes:
>
>> But beware that this uses mixed tabs and spaces, unless you have
>> configured emacs to use spaces only, as most people prefer today,
>
> Should we put up directory-local variables to promote this and a few
> other conventions?

Please do!
Jan

--

-- 
Jan Nieuwenhuizen <janneke <at> gnu.org> | GNU LilyPond http://lilypond.org
Freelance IT http://JoyofSource.com | Avatar®  http://AvatarAcademy.nl  

_______________________________________________
lilypond-devel mailing list
lilypond-devel <at> gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Permalink | Reply |
headers
Bernard Hurley | 10 Aug 2012 13:07
Gravatar

Re: GOP2-4 - C++ and scheme indentation

On Fri, Aug 10, 2012 at 12:28:35PM +0200, Jan Nieuwenhuizen wrote:
> David Kastrup writes:
> 
> > Keith OHara <k-ohara5a5a <at> oco.net> writes:
> >
> >> But beware that this uses mixed tabs and spaces, unless you have
> >> configured emacs to use spaces only, as most people prefer today,
> >
> > Should we put up directory-local variables to promote this and a few
> > other conventions?
>

On the subject of directory-local variables, some people might find this trick useful:
http://syntaxexclamation.wordpress.com/2011/08/11/set-the-root-directory-of-a-project-in-emacs-with-dir-locals-el/

Bernard
Permalink | Reply |
headers
Ian Hulin | 9 Aug 2012 12:48
Picon
Gravatar

Re: GOP2-4 - C++ and scheme indentation

Hi Jan,

I'm don't mean to be snarky here but please look at the comments below.

Cheers,
Ian Hulin

On 09/08/12 11:21, Jan Nieuwenhuizen wrote:
> Graham Percival writes:
> 
>> ** Motivation
>>
>> New contributors sometimes struggle to follow our indentation and
>> code style
> 
> Yes, that's bad.  Do we explain that we're a GNU project and as
> such use GNU coding style?  Together with a pointer to the info
> node *(standards)Formatting, that could help.
> 
>> – this is especially difficult when parts of our
>> existing source code doesn’t have a consistent style.
> 
> Yes, and even more so if we don't explain what the style is?
> 
> What could help, though, is to just accept small patches that have
> formatting problems, run C-x h C-M-\ , tell them thank you and show
> them the reformatted diff from C-x v = ?
> 
I think you missed/overlooked this in Graham's original post:
(Continue reading)

Permalink | Reply |
headers
Marc Hohl | 9 Aug 2012 12:50
Picon
Favicon

Re: GOP2-4 - C++ and scheme indentation

Am 09.08.2012 11:01, schrieb Graham Percival:
> http://lilypond.org/~graham/gop/gop_5.html
>
> ** Proposal summary
>
> Speaking academically, scheme code style is a “solved problem”.
> Let’s pick one of the existing solutions, and let a computer deal
> with this. Humans should not waste their time, energy, and
> creativity manually adding tabs or spaces to source code.
>
> C++ will remain as-is, using astyle 2.02 (not astyle2.02.1) with
> scripts/auxiliar/fix-scheme.sh
Just nitpicking:

scripts/auxiliar/fixcc.py

Marc

_______________________________________________
lilypond-devel mailing list
lilypond-devel <at> gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Permalink | Reply |
headers
Trevor Daniels | 10 Aug 2012 09:32
Picon

Re: GOP2-4 - C++ and scheme indentation

Graham Percival wrote Thursday, August 09, 2012 10:01 AM

> http://lilypond.org/~graham/gop/gop_5.html

> 
> ** Proposal summary
> 
> Speaking academically, scheme code style is a “solved problem”.
> Let’s pick one of the existing solutions, and let a computer deal
> with this. Humans should not waste their time, energy, and
> creativity manually adding tabs or spaces to source code.

I'm not sure I agree with this.  I've not written much Scheme,
but indenting it while writing it seems essential to me.  Without
reasonably correct indentation it's difficult to avoid problems.
It is useful to use an editor which highlights matching ( ), but
that's all I find I need.
 
> Scheme will be indented with a yet-to-be written
> scripts/auxiliar/fix-scheme.sh, which does the same thing as
> emacs.

This will certainly be useful to ensure uniform indentation,
which helps future comprehension.  Should be run as an
administrative task, say before a new release, rather than
as a requirement imposing yet another burden on a developer.
For example, tabs are useful while a single developer is
writing code, but a pain if entered into the code base.  The
question is, what is the best way of removing them?

> Emacs is not an answer; nobody wants to install 50 megabytes just
(Continue reading)

Permalink | Reply |
headers
Graham Percival | 10 Aug 2012 16:26
Picon
Favicon

Re: GOP2-4 - C++ and scheme indentation

On Fri, Aug 10, 2012 at 08:32:04AM +0100, Trevor Daniels wrote:
> Graham Percival wrote Thursday, August 09, 2012 10:01 AM
> 
> > Scheme will be indented with a yet-to-be written
> > scripts/auxiliar/fix-scheme.sh, which does the same thing as
> > emacs.
> 
> This will certainly be useful to ensure uniform indentation,
> which helps future comprehension.  Should be run as an
> administrative task, say before a new release, rather than
> as a requirement imposing yet another burden on a developer.

Admin task: agreed, just like fixcc.py.  I've just run fixcc.py
and pushed to staging.  The scheme indentation would happen in a
similar manner.

- Graham
Permalink | Reply |

Gmane