4p7n
last updated 3 years ago by Baseline #
So the only comment I ever got on this, when it lived at its old location, was that it missed the intended audience and should be in an appendix instead of as an intro to Classes. Thoughts on this?
I do agree that I spend too much time describing what a class is (too much time for non-newbies), but I also believe that documentation filled with examples will teach a concept better than anything else.
Comments
That's kind of what I was thinking. Before we do that, I think I'd want to add some headers to break this up a bit better. Headers will also let us say "If you already understand the concept of classes, then skip ahead to X".
I won't have time till next week though, all my school projects and exams will be done by Tuesday.
Baseline 3 years ago #
I think this is a good, well-written tutorial, but (IMO) it's let down by your use of 'A 3rd Grade CLASS' as an example - the two uses of the word 'Class' are confusing I think, and i can only imagine that this will be the same for the target audience, some of whom may not have English as a first language. Maybe it's possible to cut out some of the 'academic class of students' classes, eg. '... a teacher of the third-grade...' not '...a teacher of a third-grade class'? I think this is a better introduction to classes than the existing one, but the existing one contains a lot of essential stuff too. Perhaps Classes I, Classes II, with your version (Classes I) after Node5-data structures? (Also, I think you should use new-style classes).
gerard 3 years ago #
Yeah... I was trying to be funny by calling it "A 3rd Grade CLASS"... Mission failed, I suppose. I have no strong emotional attachment to it, or any other use of the word "class" in that context. I'll change that sometime next week (or of course anyone else is invited to do it for me).
And I'm definitely not advocating that this become the new Classes document, I wrote it to be the new introduction. As Fredrik suggested, it might work if my new stuff was just inserted in front of the current intro. The stuff in the current intro is useful, and should be around somewhere, but a new reader probably shouldn't be assaulted with scopes and namespaces before seeing a single example of a simple class.
Baseline 3 years ago #
Well, it's just IMHO and all - maybe others would disagree. I suppose this is the difficulty of writing or evaluating a tutorial, you're always trying to put yourself in someone else's shoes. I've added an alternative intro anyway, if you'd like to consider it. (it's at the end)
gerard 3 years ago #
Yeah, I like yours better. Feel free to put it in, I've got to go study!
Baseline 3 years ago #
Oh, and I forgot to mention, I purposely didn't use new-style classes for this introduction, because it means one less thing where we have to say "Trust us, we'll explain it later". Also note that I was the one that changed the current Classes documentation to use all new-style classes, so there is documentation describing one vs. the other.
Baseline 3 years ago #
Wouldn't it be better to just use new-style classes from the start. You tell here that syntax is
class Student:
you might as well tell that it's:
class Student(object):
When people come back to the tutorial if they've forgotten how to create a class, and google sends them to this page, I think it would be better if it's written new-style here.
chrisn 3 years ago #
+1 for using new-style classes from the beginning. Starting with tutorial, one presumably do not want to learn old features that are going to be deprecated later. And it is easy to understand that "object" means "the core of all objects". A small notice about old style classes somewhere would be fine. It is important (in a tutorial) to say "prefer this", "do not do this". Beginners (does not matter how experienced in other languages) need to be lead in the best direction. If they have to decide what is better to use on their own, they could be disappointed, misleaded, or simply delayed in the learning. Being a teacher, one have to show the authority to say "this is the best way for you, but not the only one".
pepr 3 years ago #
"core of all objects" seems like it'd be an incredibly confusing statement or idea for a beginner. By using a new-style class right at the beginning, you suddenly have the user faced with the idea of inheritance, and of the base object type.
And I don't think we're putting a decision into the hands of the user in terms of whether they should use new or old style. I explcitly say in 9.2 that they should use new-style. It's only a problem to a user that decides to stop reading the tutorial right here.
All I wanted to do with this section was introduce the concept and basic use of classes, which is easier when you're not adding new-style into the mix. Note again that in section 9.2, all the classes use new-style, because at that point, the user understands what a class is, and we can begin adding to that.
Baseline 3 years ago #
Don't know if it works or not, but I've altered my alternative intro to mention objects, which would make it easier to write 'class Student(object)' but without having to talk about new-style/old-style.
gerard 3 years ago #
(update: fixed markup)
Just some more thoughts. Although I really like the style of this new section - informal, chatty, hands-on - it's slightly at odds with the plainer, dryer style of the rest of the tutorial. It feels like it's for a different, less-experienced audience. This fits in with an idea I keep having when reading the wiki - what about two tutorials, a beginners' and an intermediate? I imagine the Beginners tutorial as a kind of 'Python in 24 Hours' - something that someone serious could complete over a weekend, and that would give a good grounding in the basics. Then the Intermediate tutorial would be more in-depth, more real-world - basically the existing tutorial, but without whatever is covered in the Beginners.
Suggested Beginners' Tutorial:
- Audience1 - someone with experience of another language(s) who wants to learn Python from the ground up, possibly no OOP experience
- Audience2 - someone with no programming experience but who doesn't want their hand held and is prepared to roll their sleeves up, maybe a technical/scientific background.
- Using Python as a calculator - basic numeric types and operations, logical operators, precedence
- Strings, lists, dictionaries
- Control flow: if, for, while, range()
- Functions, args/*kwargs
- Introduction to classes/OOP
I understand that there are existing Beginners tutorials but I'm also thinking of this as a 'pruning' operation for this wiki. Obviously it's a big departure from the existing situation, but food for thought at least.
gerard 3 years ago #
If the goal was to create a nice hypertext version only, providing different paths through the tutorial would of course be easy. But I'm pretty sure the powers-that-be won't accept a hypertext-only version as a replacement for the current tutorial. Hmm. Maybe it would work if we just inserted this one before the current one?
effbot 3 years ago #