"m...@mikesolomon.org" <m...@mikesolomon.org> writes: > On 13 févr. 2013, at 12:02, Werner LEMBERG <w...@gnu.org> wrote: > >> >>>> It is just a matter of writing documentation strings as you invent >>>> new callbacks. Pretty much a no-brainer not needing any >>>> organization. >>> >>> It is definitely a brainer, as it would require retroactively >>> documenting 276 MAKE_SCHEME_CALLBACKs. It would take coordinated >>> effort to get all of this stuff documented. >> >> You are missing David's point, I think. He wonders why you are coding >> callbacks without writing a documentation string. >> > > Because when I started coding for the project, there was not a single > use of MAKE_DOCUMENTED_SCHEME_CALLBACK whereas there are currently 276 > uses of MAKE_SCHEME_CALLBACK. All my programming education has come > from reading LilyPond source code, so I tend to follow the conventions > therein.
The "conventions" are two programmers in the same room, one occasionally peering over the other's shoulders, working on different angles of the same project and talking about how to interface rather than writing it down. So the problem is that you are missing how they communicate. In the current LilyPond project, one communicates with comments. Partly with code, but like science and religion, code only talks about "how" and never about "why", and we need to address the latter since our code does not just evolve from basic principles but indeed hopefully has some "intelligent design" behind it. And not every programmer has the time to build particle accelerators in order to figure out the design. So we need to tell the story, and our scripture is written out in comments. Not all too many of them. But that is not an advantage. > I would rather make a concerted effort where people decide on a style > for documenting our API (standardizing function names, documentation > style, etc.) and then we do it rather than doing a piecemeal job. Mike, you can either increase the ratio of undocumented functions and APIs whenever you add new ones, or you can decrease it. The latter is not all too hard, so it makes sense to go for it. > Someone needs to lead this. That's just an excuse for not documenting anything. I don't buy your premise that things need to get worse until some hero appears and actively makes them better. > Graham did this sort of thing for documentation a few years back and > it was an excellent idea. The discussion could be organized in the > same way as GOP and GLISS stuff. It is not a matter of "discussion". It is a manner of making it a principle to write down what one was thinking instead of just coding the outcome, whenever it is relevant to understanding code. -- David Kastrup _______________________________________________ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
