*TEACHER TO TEACHER: PYTHONIC NOTES* *1. Docstrings Versus Comments*
In teaching Python quite a bit, I find even pro programmers get confused about docstrings, as many languages have nothing quite like them. Your audience is not readers of your source code, which they may not have, but users of your API. Through help( ), they discover how to use your module or package. A bad habit with some students that is best dealt with in Beginner Python, is using multi-line string blobs, randomly placed, in place of comments using #. My understanding is this bloats the .pyc files with unnamed strings in a way that benefits neither help( ) users nor source code readers. Wasted bytes, in other words, another word for "sin" in programming. So my practice is to point out that docstrings, properly used, go only at the beginning of specific constructs: modules, functions, classes, methods. *2. "Who Am I" Attributes* The help on __doc__ belongs in the same section as help on __name__ and even __file__ as these are likewise attributes at the module level, which is where our course series first mentions docstrings (Lesson 1, Project 1 is already docstring aware). [1] *3. Dual Mode Modules (Stars Versus Extras)* __name__ == "__main__" is another one to dwell on by the way. A common misapprehension is every module needs one, whereas it's mostly useful for "dual use" modules that make sense to run top-level, and to import. Some modules play either in one role (supporting cast) or the other (starring role), but not both, so would not need this divider. The math module is a good example of one we import for its worthy extras, but do not run directly. *4. Back to the Trees! Show the Ropes!* When working with true beginners, remember that we've "returned to the trees" (like monkeys) in the sense that a file system is a fanning tree of subfolders. Not everyone comes to programming equipped to navigate using the underlying chdir / cd tools, let alone tools for digging new subfolders (mkdir etc.). Yes, very basic stuff but allow the language they're newly learning to serve as the file system API right away. Pros need the same info. Get to os.path in other words, early for the benefit of those needing "you are here" orientation. Path issues are the bane of new coders. Many a would be Java programmer has died in the Wilderness of Path Confusion.
_______________________________________________ Edu-sig mailing list Edu-sig@python.org https://mail.python.org/mailman/listinfo/edu-sig
