[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Uses single algorithm for side-position spacing. (issue 6827072)
From: |
address@hidden |
Subject: |
Re: Uses single algorithm for side-position spacing. (issue 6827072) |
Date: |
Sun, 11 Nov 2012 23:53:12 +0100 |
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
Re: Uses single algorithm for side-position spacing. (issue 6827072), k-ohara5a5a, 2012/11/12
Re: Uses single algorithm for side-position spacing. (issue 6827072), k-ohara5a5a, 2012/11/17