From a2645ee5ae61dc09e1f534441fa415a22fc37f52 Mon Sep 17 00:00:00 2001 From: Simon Wendsche Date: Thu, 27 Feb 2020 14:34:00 +0100 Subject: [PATCH] add a document explaining mandatory coding guidelines --- doc/code_style.md | 2 ++ doc/mandatory.md | 27 +++++++++++++++++++++++++++ 2 files changed, 29 insertions(+) create mode 100644 doc/mandatory.md diff --git a/doc/code_style.md b/doc/code_style.md index d11b7f34..06aec120 100644 --- a/doc/code_style.md +++ b/doc/code_style.md @@ -5,6 +5,8 @@ The most important stuff: * classes use CamelCase (except where Blender needs special class names, e.g. operators) * methods and functions are lowercase, words separated by underscores: update_objects() * "private" methods/members start with a leading underscore: _internal_update() +* Property descriptions must never end with a dot. +* Enum identifiers should be valid Python identifiers (don't contain spaces, don't start with a number etc.) For UI texts (buttons, tooltips, panel names) we follow the Blender guidelines: https://wiki.blender.org/index.php/Dev:Doc/Code_Style#UI_Messages diff --git a/doc/mandatory.md b/doc/mandatory.md new file mode 100644 index 00000000..e889e85d --- /dev/null +++ b/doc/mandatory.md @@ -0,0 +1,27 @@ +The stuff in the code_style.md document should be followed, but it is ultimately just about +the readability of the source code. +The following is really important though. If these guidelines are not followed, it can cause +massive problems - and not just now, but also years in the future. + +### Enums + +**Always** add an index for each element. +If the index is missing, we can not reorder elements later and we can not rename identifiers +without breaking old .blend files. + +Wrong: +```python +items = [ + ("first_item", "First Item", "This is the first item"), + ("second_item", "Second Item", "This is the second item"), +] +``` + +Correct: +```python +items = [ + ("first_item", "First Item", "This is the first item", 0), + ("second_item", "Second Item", "This is the second item", 1), +] +``` +(note the 0 and 1 after the descriptions)