Hi Florent, On Fri, Jun 11, 2010 at 9:32 PM, Florent Hivert <florent.hiv...@univ-rouen.fr> wrote:
<SNIP> > sage/monoids/monoid.py I think this module should stay put. Here is a dependency chart based on that module: monoids.monoid.Monoid_class --> monoids.free_monoid.FreeMonoid_class --> monoids.string_monoid.StringMonoid_class where the relation a --> b means that a is used by b. From monoids.string_monoid.StringMonoid_class, various alphabets are defined. These alphabets are extensively used in various cryptography modules, e.g. * crypto/classical_cipher.py * crypto/classical.py * crypto/cryptosystem.py * crypto/stream_cipher.py * crypto/util.py * crypto/public_key/blum_goldwasser.py * crypto/block_cipher/miniaes.py * crypto/block_cipher/sdes.py > sage/structure/element_py.py I have looked through that file and have doctested the Sage 4.4.4.alpha0 library with that file removed. So far no failures, which doesn't mean that structure/element_py.py isn't used anywhere else. But then again, I don't understand the logic of this module. Some people maintain that the documentation is in the code and terseness is desirable. In the case of structure/element_py.py, I just feel stupid and ignorant about what it's supposed to do. Remember, a reason why you meticulously document your code is that months later, when you're no longer interested in maintaining that piece of code, you don't want to hear complaints about how to use your code and/or the purpose it serves. Here's a worst case scenario taken from “Lecture 12: FOSS Culture” of the ANU course [1]: <quote> From: xxxxx Date: Fri, 9 Feb 2001 21:07:09 +0900 To: ru...@rustcorp.com.au Subject: Dear Sir, I have always wanted to flame you, however I never really had any good reason to do so. While your software creations were always egoistical and underdocumented, nothing really pushed the mark, yet. Until today, when I downloaded your “Linux 2.4″ call graph utility. So, when is your next absolute-next-to-worthless but oh-so-cool-because-it’s-from-rusty-russell piece of software coming out? Why the f*** don’t you focus on documenting things instead of writing useless shit that “takes about 8 hours to run on my mobile pII laptop” or “generates about 180mb of vector postscript”. How about another example. I heard you were involved with that atrocity called “netfilter”. Sure, it might have nice features and I am still considering using it, but WRITE SOME F***ING DOCS before you release complex shit like this for people to use! When I goto that netfilter site, I don’t give a flying raging f*** who submitted 31337 lines of code to whatever f***ing netfilter module. That’s your egoistical shit, and I could care less about it. …… (more rants delted) … Uhm, that’s all I can think of right now. xxx (name deleted) </quote> Indeed, a complaint with strong language. But you get the general idea about having good documentation. For reference, I have collected some resources [2] on how to write good documentation. > sage/structure/element_verify.py I get the feeling that this module is about code analysis for Cython modules. I think it might come in handy later on when someone needs to write a code analysis framework. They might not use all of structure/element_verify.py, but I suspect that that module could provide a starting point on how to proceed. But then again, there are various open source code analysis tools around for Python. I'm not sure about Cython. For Python, I often use these tools when I review patches or improve the Sage library: * pep8 * pychecker * pyflakes * pylint * flymake They're good at catching common mistakes, errors, omissions, etc. I would like to know of any similar tools for Cython. In the absence of such tools for Cython, I guess I would continue on spending lots of time meticulously study Cython code, essentially manually trying to perform tasks that could otherwise be automated via a lint-like tool. > sage/misc/typecheck.py As with structure/element_py.py, the module misc/typecheck.py just makes me feel stupid when it comes time for me to try to use it. A tool that makes one feel stupid isn't making a good impression on that person, and would drive the person away from using it. To me, the module is very under-documented, doesn't follow PEP 008 coding conventions, and very badly formatted. I let others in the Sage community form their own judgements about the removal of this module. > This remark also hold for the following typecheck function in > sage/misc/misc.py > ################################################################# > # Type checking > ################################################################# > def typecheck(x, C, var="x"): > """ > Check that x is of instance C. If not raise a TypeError with an > error message. > """ > if not isinstance(x, C): > raise TypeError, "%s (=%s) must be of type %s."%(var,x,C) This looks to me like, how can I put it, redundant code. I'm basing my judgement on the idea that I would write such code at the point where I want to do sanity checking, instead of calling a function that does the same thing, but doesn't allow me to customize my exception message. I would personally vote for removal of this function. [1] http://cs.anu.edu.au/students/comp8440/lectures.php [2] http://wiki.sagemath.org/DocumentationProject -- Regards Minh Van Nguyen -- 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
