On 11 nov. 2012, at 20:57, d...@gnu.org 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 _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
