On Sun, Apr 20, 2008 at 5:13 PM, TimDaly <[EMAIL PROTECTED]> wrote: > > > I'm surprised by how convinced you are that using a specific > > technology/language -- literate programming -- can be a silver > > bullet to solve such a difficult problem. I think peer review, > > and many many other things, are steps in the right direction, > > but *not* solutions to the problem. I think it's just a difficult > > problem, with no easy solutions. > > Actually, I don't think that literate programming is a silver bullet. > But I do think that it exposes the real work that is needed to make > something like Sage live (see my power-of-3 screed a while back). > > If Gary is going to figure out "the way up the mountain face" > wouldn't it make sense to write it down so others can read it? > Or is it better to let the next person figure it out (badly) from > reading the code and inferring the path?
Yes, it would be great if Gary could write that down, write a book about it and let us know how it went. But Gary has only finite time, and lots of things he wants to do with it. He has to choose what the best use of his time is. And there's a lot of work that goes into making a book that has little to do with a direct explanation of what this line/section of code does. There's a distinction between the style of "literate programming" and writing documentation within your code so that others can understand what it's doing. I understand the argument that you want the writing to be "explanation-centric" rather than "code-centric." But writing documentation in other ways can serve to explain what you're doing to future readers as well. For me, I'm happy when I write good comments: I don't want to take the time to write a book surrounding my code. David --~--~---------~--~----~------------~-------~--~----~ To post to this group, send email to sage-devel@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/sage-devel URLs: http://www.sagemath.org -~----------~----~----~----~------~----~------~--~---
