On Wed, 2012-01-18 at 23:45 +0100, Burcin Erocal wrote: > On Wed, 18 Jan 2012 12:26:33 -0800 (PST) > kcrisman <kcris...@gmail.com> wrote: > > > Publishing Computational Mathematics, by Tim Daly (of Axiom, a > > frequent contributor on sage-devel) > > http://www.ams.org/notices/201202/rtx120200320p.pdf > > Literate programming is not just adding comments to code, but here are > a few numbers nevertheless... > > FriCAS (I couldn't find Axiom on ohloh.net): > https://www.ohloh.net/p/fricas > # of lines of code: 1218007 > # of comment lines: 205615
http://en.wikipedia.org/wiki/Axiom_computer_algebra_system http://axiom-developer.org Axiom has a project focus to become a literate program. FriCAS has a project focus to compete with Mathematica. Due to this philosophical difference the Axiom project forked. New computational mathematics is always interesting but it is more important to make sure that the code can be modified and maintained without devoting your life to the task. Projects die when the original authors leave. Sourceforge has 100,000 piles of "dead code". In order to keep Axiom "alive" it must be possible to understand, modify, and maintain it. I firmly believe that literate programming is the only technology that can achieve this. Axiom is being rewritten to be fully literate. The code is being moved from a "tree of little files" to volumes with a particular focus. There are currently 21 volumes. These volumes contain actual executable source code which is extracted at build time. So the code you see in the books is the actual source code. There are still many small files to rewrite and distribute into their proper locations and there is still a great deal of explanation to be added to the volumes. However, this project has "a 30 year horizon" so this huge task is "right on schedule". > > Singular: > https://www.ohloh.net/p/Singular > # of lines of code: 456764 > # of comment lines: 73429 > > Sage: > https://www.ohloh.net/p/sage > # of lines of code: 474866 > # of comment lines: 551813 Literate programming has nothing to do with comments. They are completely orthogonal. Think of literate programs as works of literature. You are telling a story (of why the code exists and what you are trying to solve). You need to motivate the characters (so procedures need to be introduced at the proper time in the explanation, not when the compiler needs it). You are trying to write a story for another human being, not code comments for the programmer. Write down the theory behind the code. The "Hawaii test" is a good benchmark. Can you bring a new person on the project, give them the literate books, send them away to an all-expense paid, 2 week vacation to Hawaii, and when they return they can maintain and modify the program as well as the original authors? I have found 2 literate programs that I consider examples: "Lisp in Small Pieces" by Queinnec (ISBN 0-521-56247-3) "Implementing Elliptic Curve Cryptography" by Rosing (ISBN 1-884777-69-4) I claim that literate programming improves code in 3 ways: A) the original programmer discovers errors while writing up the full explanation for peer review B) peer reviewers gain a deep understanding of the problem and can critique the original motivation for the code including how well the implementation covers it. C) future programmers can correctly modify and maintain the code in the spirit it was written. All of these are just opinions at this point but they can be tested. I am trying to find a university willing to run a test of hypothesis B. Students would be given either a literate program (e.g. Rosing's book) or the original source code (e.g. Rosing's downloadable source) and asked questions to test their comprehension, such as given #DEFINE NUMBITS 158 what is the significance of "158"? Do you know? Elliptic curve code uses modular polynomial arithmetic which Rosing explains but would be really hard to "reverse engineer" from the source code. > > Gap wasn't available for comment at the time of publication: > https://www.ohloh.net/p/gap-system > > > This is also a good occasion to paste "sage -coverageall" output from > 5.0.prealpha0: > > Overall weighted coverage score: 86.3% > Total number of functions: 28917 > We need 1056 more function to get to 90% coverage. > We need 2502 more function to get to 95% coverage. > We need 3658 more function to get to 99% coverage. Test coverage is an excellent idea. Commenting code is an excellent idea. Choosing descriptive variable names is an excellent idea. Code standards are an excellent idea. All of these have nothing to do with a literate program. Literate programming can be done in any language. I wrote an example using HTML: http://axiom-developer.org/axiom-website/litprog.html Are you creating computational mathematics useful for future generations or will they start yet-another- from-scratch-computer-algebra-system to replace Sage? Raise your game. Make your code "live". Make it literate. Tim Daly -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
