Tutorial is difficult to understand.

[Vernon Cole]

I found it very difficult to follow the Storm tutorial the first several times I tried to read it.

I was finally able to grasp the concepts when I worked through the tutorial refactoring the sample code with dotted module names.

In the Python Tutorial, BDFL states: "Note that in general the practice of importing * from a module or package is frowned upon, since it often causes poorly readable code."

In the article "Idioms and Anti-Idioms in Python" in the Python 2.5 documentation library, the first heading under "Language Constructs You Should Not Use" is "from module import *."

Isn't it a bit paradoxical then, that the first example line in the Storm tutorial is: "from storm.local import *"?

I have edited the tutorial to enhance its readability for newcomer's sake. A patch is forthcoming.

[James Henstridge (jamesh)]

I generally consider "from storm.locals import *" as a short cut for use in the interactive shell, and usually use direct imports from the other modules in the storm package for real programs.

Your proposed changes to the tutorial do not match how we generally use Storm, so I would not be in favour of those changes.

[Vernon Cole (vernondcole)]

The key phrase in your response was "how *we* generally use Storm."
I am certainly not advocating that an experienced Storm programmer would want to change their way of writing code, or would want to use a construct like "as S" in production work. (I usually do, because I expect my work to be understood by non-expert readers.)
  In this case, the dotted module name works as training wheels, to help the newbie get started by reminding him or her where the name comes from.
  Please reconsider.

[James Henstridge (jamesh)]

I'd generally recommend that new Storm programmers use Storm the same way we currently use Storm (which is what the tutorial reflects).

I don't think it makes sense to tell new programmers to use the library in a different way to experienced programmers. If the API is unclear then we should address that, but preferably not by using idioms used by other existing Python libraries rather than making up new ones.

[Jamu Kakar (jkakar)]

[1]

Changing the coding style to use nerdyCaps is not a good idea
because the Storm code base itself uses lower_case_with_underscores.
We shouldn't fragment the formatting style.

Similarly, using 'my' in front of variable names is not a good idea
because it differs from the established coding style.

[2]

+We'll use "as S" to make typing easy, but still document that
+the new names we will be using are part of Storm.
+Some experienced programmers prefer "from storm.locals import *".

I don't find that using S. adds anything to the tutorial. In fact,
it's more confusing to me. Also, I don't think experienced Storm
developers use "from storm.locals import *", other than in the
interpreter when playing around.

I would prefer to see the tutorial changed to use qualified imports,
to make it clear where things come from. For example, we could
change this:

"""
Now we define a type with some properties describing the information
we're about to map.

{{{#!python
>>> class Person(object):
... __storm_table__ = "person"
... id = Int(primary=True)
... name = Unicode()

}}}
"""

to

"""
Now we define a type with some properties describing the information
we're about to map.

{{{#!python
from storm.locals import Int
from storm.locals import Unicode

>>> class Person(object):
... __storm_table__ = "person"
... id = Int(primary=True)
... name = Unicode()

}}}
"""

which at least makes it clear where Int and Unicode come from.

[3]

+In other cases, create_database() does not actually *create* a database. It would be
+more precise to say that it defines a connection to an existing database.

I don't think this really helps. Debating naming style in the
tutorial doesn't help. I would argue that the create_X naming
convention is well established as being about object creation, and
thus makes sense here.

I'm -1 on this branch.