2013-03-28 14:37:17 -07:00
|
|
|
|
2013-03-29 08:46:32 -07:00
|
|
|
Style
|
|
|
|
=====
|
|
|
|
|
|
|
|
* For indentation, use *four space characters* per level of indentation.
|
|
|
|
|
2013-03-30 06:00:50 -07:00
|
|
|
* When comparing C pointers, use == and != instead of the python operator "is".
|
2013-03-30 15:22:33 -07:00
|
|
|
This makes a visual distinction.
|
2013-03-30 06:17:52 -07:00
|
|
|
|
|
|
|
Design patterns
|
|
|
|
===============
|
|
|
|
* From "The Zen of Python":
|
|
|
|
|
|
|
|
Beautiful is better than ugly.
|
|
|
|
Explicit is better than implicit.
|
|
|
|
Simple is better than complex.
|
|
|
|
Complex is better than complicated.
|
|
|
|
Flat is better than nested.
|
|
|
|
Sparse is better than dense.
|
|
|
|
Readability counts.
|
|
|
|
Special cases aren't special enough to break the rules.
|
|
|
|
Although practicality beats purity.
|
|
|
|
Errors should never pass silently.
|
|
|
|
Unless explicitly silenced.
|
|
|
|
In the face of ambiguity, refuse the temptation to guess.
|
|
|
|
There should be one-- and preferably only one --obvious way to do it.
|
|
|
|
Although that way may not be obvious at first unless you're Dutch.
|
|
|
|
Now is better than never.
|
|
|
|
Although never is often better than *right* now.
|
|
|
|
If the implementation is hard to explain, it's a bad idea.
|
|
|
|
If the implementation is easy to explain, it may be a good idea.
|
|
|
|
Namespaces are one honking great idea -- let's do more of those!
|
|
|
|
|
2013-03-29 08:46:32 -07:00
|
|
|
Tips
|
|
|
|
====
|
|
|
|
|
|
|
|
* cython -a will generate a report that shows your cython code, and each line
|
|
|
|
can be expanded by clicking to show the generated C code.
|
|
|
|
|
|
|
|
* cython does automatic dict <-> struct conversion with basic struct members
|
|
|
|
|
|
|
|
Ideas
|
|
|
|
=====
|
|
|
|
|
|
|
|
* Use a decorator for _METHOD_DEPRECATED
|
2013-03-30 15:22:33 -07:00
|
|
|
|
|
|
|
Discussion
|
|
|
|
==========
|
|
|
|
|
|
|
|
* When comparing C pointers, use == and != instead of the python operator "is".
|
|
|
|
This makes a visual distinction between C and py code and don't confuse the
|
|
|
|
reader as "==" and "is" has different meaning in python.
|
|
|
|
^
|
|
|
|
This last clarification is not true. We're actually comparing whether two
|
|
|
|
references are the same (pointer comparison) which is what the operator
|
|
|
|
"is" does in Python, not whether their value is the same, which is what
|
|
|
|
"==" does in Python.
|
|
|
|
|
|
|
|
This is a direct quote from Cython developer Stefan Behnel:
|
|
|
|
"If a user wants pointer comparison, "is" is the most explicit operator
|
|
|
|
w.r.t. Python semantics."
|
|
|
|
|
|
|
|
I don't mind if it's "==" for visual difference, but confusing everyone
|
|
|
|
by first telling them the operators' meaning in Python and then using them
|
|
|
|
in reverse is absolutely not acceptable.
|
|
|
|
|
|
|
|
/ kuuko
|
|
|
|
|
|
|
|
* Internal utility functions used in the bindings must start with an
|
|
|
|
underscore and must have the shortest name as possible.
|
|
|
|
^
|
|
|
|
This needs further discussion/expansion.
|
|
|
|
|
|
|
|
When we define a function with cdef it is not exposed to Python API.
|
|
|
|
This should be explicit enough to not need the underscore prefix, which
|
|
|
|
at best looks ugly, and at worst just plain confusing.
|
|
|
|
|
|
|
|
A function name should summarize its functionality in one clear text,
|
|
|
|
short sentence. We have both too long and too short names. And I admit to
|
|
|
|
being guilty of adding many of both.
|
|
|
|
|
|
|
|
Let's build up a short review so we can see where we stand with this and
|
|
|
|
make necessary corrections.
|
|
|
|
|
|
|
|
/ kuuko
|