Han-Wen Nienhuys <hanw...@gmail.com> writes: > On Sat, Feb 11, 2012 at 8:31 AM, <janek.lilyp...@gmail.com> wrote: > >> Well, the main point of the comment is not describing parameters, but >> the function itself. Believe me or not, we spent 10 minutes figuring >> out _what the hell_ are apes doing here and whether there are any >> bananas involved. It's stupid, i know. But there must exist a way >> of writing code that is understandable for the newcomers after second >> reading, not after 10 minutes. > > I disagree. Reading code the first time is hard, that is true, but > unless anything surprising is happening, it does not deserve a > comment. The more you read code, the easier it becomes, and think of > this as you learning how to read. In an analog: beginners books may > feature simpler words, hy-phe-na-te all words explicitly and use > pictures, but that doesn't mean literature for grownups should have > those.
The problem with much of the LilyPond code base is not that it is short in comments paraphrasing the code: I agree that those are mostly a distraction getting out of date. The problem is that it is short in comments reporting the _purpose_ of code. I've just looked at the part combiner code, and it creates complex GOOPS structures and meddles with them, and sorts things and stuff. And even though there are a few comments, those are just of the _paraphrasing_ kind. They tell you what you could have figured out on your own. They don't tell you what is actually happening according to what plan and design and where all of this is supposed to fit in why and how. Architecture is not the same as masonry. -- David Kastrup _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
