Re: Uses single algorithm for side-position spacing. (issue 6827072)

[address@hidden]

On 11 nov. 2012, at 20:57, address@hidden wrote:

> To make it short: a function needs documentation that tells its purpose
> in the overall scheme of things (for what purpose is it used), its
> outline (what does it do), its input and output.
> 

This sounds great.

> A "policy" may describe how they are formatted and whether or not they
> are used as Scheme documentation strings.
> 

This sounds even better - this is the type of thing that would be excellent.

> But whether or not there is "policy", this information _must_ be present
> or the function is incomplete.  That's not "policy" but "sanity".
> 
> As long as you don't have an argument better than "I never did that" or
> "other code does not do that", there is _no_ point in refusing to add
> this information.  In what respect will the code be better maintainable
> if you omit this information?
> 

I don't refuse to add any of these things.  I think it'd be worthwhile to have 
commenting and docstring guidelines for functions - this will help me figure 
out how to best add these things.

> If you have had a coherent design in mind when writing the code, it
> should be fresh in your memory and it is just a matter of writing it
> down.  If you did not have a coherent design in mind when writing the
> code, maybe you'll even discover something dishy when trying to describe
> the design.
> 
> So again: in what respect is the code improved by you not writing down
> what it is supposed to achieve in what context by doing what and how?

I have no problem doing this.  I learned to write LilyPond code by reading 
LilyPond code, and similarly, I learned to not write comments by reading 
LilyPond code.  So, I don't know how to write comments effectively and I need 
the help of someone who can bring this skill to the LilyPond code base.  It'd 
be great if you could open up a tracker issue and post what you believe to be a 
good template for function commenting.  I will use that model whenever I write 
a new function.

Cheers,
MS