"m...@mikesolomon.org" <m...@mikesolomon.org> writes: > On 13 févr. 2013, at 13:50, David Kastrup <d...@gnu.org> wrote: > >>> 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. > > The most time I lost in LilyPond development in my first couple years > was from reading comments that for some reason were obsolete or > non-indicative of what was actually going on.
Did you fix them? If not, why not? Bad or missing comments are _bugs_. When the computer does not understand what he is supposed to be doing, that is a bug, and when the fellow programmers do not understand what they are supposed to be doing, that is a bug. If a computer takes an inordinate amount of time running code, that is a bug, and if a programmer takes an inordinate amount of time reading code, that is a bug. If you do git log lily/include/smobs.hh, you'll notice that the last two commits were _only_ comments. Comments that put down understanding I had to derive the hard way. If you find information like that missing and figure it out the hard way, _write_ _it_ _down_ so that the next programmer has an easier job. > Once I started just reading the logic of the code, everything got much > easier. So why do you choose function names that don't make sense, variable names that don't make sense, and factor your code in a manner that does not reflect the logic of the task you are solving but rather the steps that occur as a consequence of the task? The original code by Han-Wen and Jan is code by _experienced_ programmers. Its lack of comments is a total nuisance, but the logic of the code is somewhat transparent. An excellent musician or dancer makes hard pieces appear deceptively simple to perform, reflecting their story rather than their notes. An excellent programmer is able to let the code reflect its design rather than just its operation. The damage of Han-Wen's and Jan's original coding style is not just that it makes it hard for others to work on the code. It is also setting a bad example, like an electrician soldering bulbs directly onto wires, one that is likely to cause accidents when people have no comparison to go by and get led to think that this is how things should be done. > So I am 100% pro telling the story but this needs to be done in a > coherent way. I realize that talking about user documentation is a > different issue, but I think it needs to benefit from the same > coherence and uniformity. Forget user documentation. It is not relevant to why your code is unmaintainable. >>> 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. > > This is not an excuse for not documenting anything. Every time I add > a property I document it because there is a structure in place w/ > ample examples of how to do so. Ditto for interfaces. Ditto for > LY_DEFINE. > > An API for LilyPond is a long talked about, excellent idea. There is no "API for LilyPond", and that does not even make sense. You are possibly talking about "Coding Standards" which is something totally different. APIs are for the computer talking to the computer. Coding standards are for people talking to the computer and to other people. > Once someone who is passionate about it comes up with rules about how > it is done, like C++ indentation, I will follow it to the best of my > abilities, exactly as I do for properties and interfaces and > LY_DEFINE. That's crap. If something is not obvious, write down the reasoning behind it. Whether you do it in code comments, or in documentation strings or whatever, write it down. Don't tell the story just to the computer, correction, don't tell just the _letters_ of the story to the computer (telling the story would involve proper factorization). >>> 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. > > This is where I get the most help from reviews - I add comments when > people ask me what things do. It is not obvious to me when things are > relevant and not. Mike, you write _no_ comments as a rule. That means that your code is unmaintainable crap as a rule. That does not mean that there isn't unmaintainable crap in the preexisting LilyPond code base, too. I am weeding some of it out and designing sane code paths and interfaces to replace them, fixing the logic and writing documentation. That's very hard work and takes likely more than ten times the amount of time than originally writing it took. You are _far_ too productive to make it possible for me or anybody else to go with a fine sieve through _every_ _single_ contribution of yours even in review and tell you _every_ _single_ place where things fall apart without a comment or a description or a documentation string or sensible variable names. _Wherever_ somebody could ask "what is the idea behind this?", there is a missing comment or documentation string. Yes, it is bad with the preexisting LilyPond code base, but extending LilyPond while keeping this style is making it exponentially worse. And make no mistake, even if we are talking about the quality of uncommented code: it is not rare that I encounter code where I say "this is so broken and/or handwavy and/or indecipherable, I'll bet it's from Mike" and am right far more often than I'd like. If at least the rationale behind the code were commented, it would not be such a time sink to analyze and/or fix. Now recognizing coders by their handwriting is also possible with excellent coders: it's reasonably easy to figure out whether some TeX code has been written by Heiko Oberdiek, Hans Hagen, David Carlisle, or myself. The average comment density is not particularly high, granted. But it is definitely non-zero, and it is there for basically everything of substance _underlying_ the code. -- David Kastrup _______________________________________________ lilypond-user mailing list lilypond-user@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-user
