Skip to content

Commit 721241b

Browse files
seanbuddseanbudd
authored
Merge 8353f5f into c438163 
2 parents c438163 + 8353f5f commit 721241b

12 files changed

Lines changed: 1333 additions & 869 deletions

File tree

‎devDocs/codingStandards.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ for more information.
4444
- E.G. `BrailleHandler`.
4545
* Constants should be all upper case, separating words with underscores;
4646
- E.G. `LANGS_WITH_CONJUNCT_CHARS`.
47+
- Avoid unnecesary shared prefixes in constants. Instead, use an enum for related constants.
4748
* Event handlers are prefixed with "event_", subsequent words in camel case.
4849
Note, `object` and `action` are separated by underscores.
4950
- E.G.: `event_action` or `event_object_action`.
@@ -59,6 +60,13 @@ for more information.
5960
- TBD. Ideally follows a similar style the others, and communicates if the filtering happens
6061
before or after some action.
6162
- It would also be nice to have a naming scheme that differentiates it from the others.
63+
* Enums should be formatted using the expected mix of above eg:
64+
```python
65+
class ExampleGroupOfData(Enum):
66+
CONSTANT_VALUE_MEMBER = auto()
67+
@property
68+
def _formatMember(self): pass
69+
```
6270

6371
### Translatable Strings
6472
* All strings that could be presented to the user should be marked as translatable using the `_()`
@@ -86,3 +94,11 @@ self.copySettingsButton = wx.Button(
8694
)
8795
)
8896
```
97+
98+
### Imports
99+
* Unused imports should be removed where possible.
100+
- Anything imported into a (sub)module can also be imported from that submodule.
101+
- As a result, removing unused imports may break compatibility, and should be done in compatibility breaking releases (see `deprecations.md`).
102+
* Unused imports will give a lint warning. These can be handled the following ways:
103+
- If these imports are inteded to be imported from other modules, they can be done included in a definition for `__all__`. This will override and define the symbols imported when performing a star import, eg `from module import *`.
104+
- Otherwise, with a comment like `# noqa: <explanation>`.

‎devDocs/deprecations.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
The NVDA API must maintain compatibility with add-ons throughout yearly development cycles.
2+
The first release of a year, i.e. `20XX.1`, is when the NVDA API can introduce breaking changes.
3+
4+
In order to improve the NVDA API, changes that will break future compatibility can be implemented, as long they retain backwards compatibility until the `20XX.1` release.
5+
6+
This can be done by using a version check to automate deprecation. For example, if you wish to replace usages of `foo` with `bar`. When we begin work on `NEXT_YEAR`, `foo` will no longer be part of the NVDA API and all internal usages must be removed prior.
7+
```python
8+
from buildVersion import version_year
9+
if version_year < NEXT_YEAR:
10+
foo = bar
11+
```
12+
13+
To ensure a module retains the same symbol names being importable, check across versions what is imported using the NVDA python console.
14+
```python
15+
import controlTypes
16+
dir(controlTypes)
17+
```
18+
19+
Changes different to moving or renaming symbols need to be considered carefully with a different approach.
20+
21+
Any API breaking changes such as deprecations marked for removal should be commented with the year of intended removal, and notes on how to implement the API change as an add-on developer and NVDA developer.

0 commit comments

Comments
 (0)