Code Standards

​

General Guidelines

​

Encoding

• Python files should be encoded in UTF-8
• Text files should be committed with LF line endings
• Files can be checked out locally using CRLF if needed for Windows development using git’s core.autocrlf setting

​

Indentation

• When splitting a single statement over multiple lines, just indent one or more additional levels
• Don’t use vertical alignment (lining up with the bracket on the previous line)
• This requires a new-line after an opening parenthesis/bracket/brace if you intend to split the statement over multiple lines

​

Identifier Names

​

Use Descriptive Names

• Name constants to avoid “magic numbers” and hint at intent or origin of the value
• Consider: what does this represent?

​

Functions, Variables, Properties

speakText
brailleHandler
currentFocusObject

​

Boolean Functions or Variables

• Use the positive form of the language (avoid double negatives like shouldNotDoSomething = False)
• Start with a “question word” to hint at their boolean nature

shouldSpeak
isEnabled
hasChildren

​

Classes

BrailleHandler
TextInfo
NVDAObject

​

Constants

LANGS_WITH_CONJUNCT_CHARS
MAX_BUFFER_SIZE
DEFAULT_TIMEOUT

​

Scripts

script_cycleAudioDuckingMode
script_reportCurrentLine

​

Event Handlers

event_gainFocus
event_caret
event_appModule_gainFocus

​

Extension Points

• Prefixed with pre_ or post_ to specify that handlers are notified before/after the action

• Prefixed with should_ to turn them into a question
• Example: should_doSomething

• Prefixed with filter_
• Should describe the filtering action and the data being returned
• Should communicate if filtering happens before or after some action
• Example: filter_displaySize_preRefresh

​

Enums

class ExampleGroupOfData(Enum):
    CONSTANT_VALUE_MEMBER = auto()
    
    @property
    def _formatMember(self):
        pass

​

Translatable Strings

# Translators: The name of a category of NVDA commands.
SCRCAT_TEXTREVIEW = _("Text review")

​

Multi-line Translatable Strings

self.copySettingsButton = wx.Button(
    self,
    label=_(
        # Translators: The label for a button in general settings to copy
        # current user settings to system settings (to allow current
        # settings to be used in secure screens such as User Account
        # Control (UAC) dialog).
        "Use currently saved settings during sign-in and on secure screens"
        " (requires administrator privileges)"
    )
)

​

Imports

• Unused imports should be removed where possible
• Anything imported into a (sub)module can also be imported from that submodule
• Removing unused imports may break compatibility and should be done in compatibility breaking releases

​

Handling Unused Import Warnings

1. If imports are intended for re-export: Include them in __all__ definition
   __all__ = ["SomeClass", "someFunction"]
   
2. Otherwise: Add a comment like # noqa: <explanation>

​

Considering Future Backwards Compatibility

​

Docstrings

​

When to Use Docstrings

• All public functions, classes, and methods should have docstrings
• Most internal functions, classes and methods should have docstrings, except where their purpose is clear from their name or code
• A function of more than a few lines of code is most likely not self-explanatory

​

Guidelines

• Providing type information in docstrings is discouraged - use type annotations instead
• Class-level and module-level docstrings should contain:
  • High-level overview
  • Optionally: usage examples and references to commonly used methods/functions and attributes
• Document class constructors in __init__, not at the top of the class
• Document class attributes and non-obvious public variables in a docstring immediately below the attribute

​

Learning Resources

• reStructuredText Primer from Sphinx docs
• reStructuredText markup from Python Developer’s Guide
• Sphinx’s custom reStructuredText Directives
• Sphinx’s Python Domain

​

Type Hints

​

Requirements

• All variables, attributes, properties, and function/method arguments and returns should have type hints
• No need to provide type hints for self or cls arguments to object/class methods
• Prefer union shorthand (X | Y) over explicitly using typing.Union
• Corollary: prefer T | None over typing.Optional[T]

​

Example

def speakText(
    text: str,
    priority: SpeechPriority = SpeechPriority.NORMAL,
    symbolLevel: int | None = None
) -> None:
    """Speak the given text with specified priority."""
    pass

​

Calling Non-Python Code

​

Naming Conventions

• Example: GetModuleFileName not getModuleFileName
• Pythonic names should be reserved for wrappers that provide more pythonic access to functions

​

Organization

• Windows API functions: Define in the winBindings package in modules named according to the DLL
  • Example: winBindings.kernel32
• nvdaHelper ctypes code: Define in the NVDAHelper.localLib module

​

Language Choices

Communities mirror the societies in which they exist and positive action is essential to counteract the many forms of inequality and abuses of power that exist in society.

​

Guidelines

• Avoid metaphors, euphemisms or other language with layers of meaning or negative history
• Avoid generalisations about people, cultures or countries
• Avoid ableist language
• Use gender-inclusive terminology

​

Examples of Preferred Terms

​

Running Code Style Checks

# Run linting checks
runlint.bat

# Check translatable strings
runcheckpot.bat

# Check licenses
runlicensecheck.bat