{% extends "base.html" %} {% block main %}

## Conventions

Thank you for your interest in Sketching! This page lays out some "conventions" which are general guidelines that the Sketching codebase and API typically try to follow. This page is primarily for those interested in volunteering for Sketching 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

Sketching 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: Sketching should not assert control over the rest of the code's structure or licensing.
- Pedagogical: Sketching should be usable in educational settings as additive to cirricula.
- Productionizable: Sketching should follow general Pythonic practices and be able to work as a component within a larger sophisticated engineering effort. This also means that Sketching itself must offer conceptual integrity.

We may not always achieve these goals and they may come in conflict with each other but we value them.

### Paradigm

While Sketching 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 Sketching 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.

Therefore, this project reaches a compromise: its exported types should generally follow OOP but should not force use of classes in client code. For example, it should support functional code through callback registration instead of subclassing.

### 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).

Note that some of these further efforts in education (including standardized tests) and attempt to follow commonly taught standards.

### Teach module

The "sketching.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.

This list may evolve during the lifetime of the project.
{% endblock %}