Conventions
Thank you for your interest in Sketchingpy! This page lays out some "conventions" which are general guidelines that the Sketchingpy codebase and API typically try to follow. This page is primarily for those interested in volunteering for Sketchingpy either in contributing code or documentation. Of course, we understand that rules will have exceptions and we invite contributions even if they don't follow these directions precisely. We respect that excellent developers and other community members may disagree with this guidance and invite dialogue to further refine this document's perspective. However, maintainers may ask contributors to conform to these goals before they can merge their work. Note that this does not apply to the showcase.
Coding standards
Note that this document describes approaches and norms above the requirements laid out in our code contributrions page and CONTRIBUTING.md.
Values
Sketchingpy explicitly emphasizes certain values in its design and implementation:
- Portable: User sketches should be able to move between supported platforms including desktop, web, and Jupyter with as little rewrite as possible.
- Agnostic: The library should work across many environments including in self-hosted pyscript.
- Embeddable: Sketchingpy should not assert control over the rest of the code's structure or licensing.
- Pedagogical: Sketchingpy should be usable in educational settings as additive to cirricula.
- Productionizable: Sketchingpy should follow general Pythonic practices and be able to work as a component within a larger sophisticated engineering effort. This also means that Sketchingpy itself must offer conceptual integrity.
Paradigm
While Sketchingpy wants to be agnostic, it needs to provide conceptual integrity and, thus, requires an internal unifying paradigm. That in mind, we recognize that it may be used in object oriented settings including education where OOP is typical (see introductory instruction and standardized tests as well as industry certificates). Our current perspective:
- We do not wish to force users into a strict object oriented setting like through forced subclassing.
- We want to be a good participant and follow best practices in an educational setting to model techniques in line with class materials.
- We want students with some experience to be empowered to both read the Sketchingpy codebase and to, when they desire, contribute to it.
- The Python standard library itself frequently uses objects (csv, sqlite, etc) so we expect programmers to need to interact with "class-based" code even if they aren't writing it themselves as they have to encounter it in their broader Pythonic journey.
Naming
The following naming rules are recommended:
- Class names should be nouns.
- Method and function names should be verbs.
- Event listener registers should use "on" notation as a preposition to a verb like sketch.on_step(draw).
Teach module
The "sketchingpy.teaching" module serves an important role in education and may break some of these conventions. For example, it may export members outside OOP.
Other
The following are also recommended:
- Some functionality is is likely to be unavailable in some platforms such as keyboard input, joysticks, or sound. These functions should be behind a getter (like get_keyboard) which returns None if is not available or not permitted by the user. This allows developers to probe for functionality availability.
- When supported by the renderer, multiple simultaneously running sketches should be supported.
- Documentation speaking style should be clear, concise, and professional but, where possible, should strive to set an informal and encouraging tone.
- Instance variables should be private. This is because methods are guaranteed to be consistent across platforms but variables are not.