Update Coding style documentation

.github/.wordlist.txt

@@ -41,6 +41,9 @@ AFL
 AIDL
 algs
 alloc
+allocator
+allocators
+Ambrose
 Ameba
 amebad
 amebaiot
@@ -317,6 +320,7 @@ cryptographic
 CSA
 csg
 csrrequest
+cstdint
 csu
 csv
 ctl
@@ -440,6 +444,7 @@ DNSStubListener
 docbuild
 Dockerfile
 Dockerfiles
+docstrings
 Don'ts
 DoorLock
 DoorState
@@ -565,6 +570,8 @@ FlowMeasurement
 FluorideConcentrationMeasurement
 focusable
 forkpty
+formatter
+formatters
 FOTA
 FreeRTOS
 FreeRTOSConfig
@@ -731,6 +738,7 @@ IPython
 ISCAN
 isHexString
 isLowerCase
+isort
 isUpperCase
 itemName
 iterable
@@ -878,6 +886,7 @@ MediaPlayback
 MediaTek
 MEI
 mem
+memcpy
 memdf
 MemMonitoring
 menuconfig
@@ -933,6 +942,7 @@ mv
 MX
 mydir
 MyPASSWORD
+mypy
 MySSID
 NAMESERVER
 NAMESPACE

docs/style/CODING_STYLE_GUIDE.md

@@ -0,0 +1,162 @@
+# Coding Style Guide
+
+_Revision 6_ _2024-10-28_
+
+This guide provides a small set of code guidelines used in the SDK. This guide
+reflects the currently accepted style practices for the SDK and is subject to
+change.
+
+The SDK was seeded from multiple different projects and contains contributions
+from many different companies and the SDK code therefore uses several different
+coding styles throughout the code base. Stylistically, code should attempt to
+conform to the dominant style of the code being modified, while also adhering to
+the guidelines below.
+
+## Language standard
+
+Code in the SDK conforms to the following standards. Changes to the C++ standard
+happen infrequently and there has been only one change from C++14 to C++17 over
+the course of the SDK lifetime. Changes to the Python version happen more
+frequently.
+
+| Language | Version |
+| -------- | ------- |
+| C++      | C++17   |
+| Python   | 3.10    |
+
+Product-specific software may elect to use later standards in their own work.
+
+## Coding Guidelines
+
+### Common
+
+#### When in Rome
+
+The most important convention and practice in the Matter SDK repo is "_When in
+Rome..._", per the quote below.
+
+[quote, St. Ambrose]
+
+---
+
+If you should be in Rome, live in the Roman manner; if you should be elsewhere,
+live as they do there.
+
+---
+
+Your extensions or fixes to existing code should match the prevailing of the
+original code.
+
+If you find the conventions so foreign or otherwise confusing, it may be best to
+let whoever owns the file make the necessary changes or seek the counsel of
+others in the group to find out what the right thing to do is. Never just start
+changing code wholesale for personal reasons without consulting others first.
+
+#### Commenting Out or Disabling Code
+
+Unused code shall not be disabled by commenting it out with C- or C++-style
+comments or with preprocessor `#if 0 ... #endif` semantics.
+
+#### Auto-formatters
+
+We use the following auto-formatters on code:
+
+| Language   | Formatter          | Style File                                                                                                  |
+| ---------- | ------------------ | ----------------------------------------------------------------------------------------------------------- |
+| C++        | clang-format       | [.clang-format](https://github.com/project-chip/connectedhomeip/blob/master/.clang-format)                  |
+| ObjectiveC | clang-format       | [.clang-format](https://github.com/project-chip/connectedhomeip/blob/master/.clang-format)                  |
+| java       | google-java-format | N/A                                                                                                         |
+| Python     | pep8, isort        | [.restyled.yaml](https://github.com/project-chip/connectedhomeip/blob/master/.restyled.yaml) (command line) |
+| YAML       | prettier           | None                                                                                                        |
+| JSON       | prettier           | None                                                                                                        |
+| markdown   | prettier           | None                                                                                                        |
+
+All pull requests run formatting checks using these tools before merge is
+allowed. Generated code is not run through restyle.
+
+### C++
+
+#### Use C++ _cstdint_ for Plain Old Data Types
+
+Standard, scalar data types defined in _cstdint_ should be used for basic signed
+and unsigned integer types, especially when size and serialization to
+non-volatile storage or across a network is concerned.
+
+Examples of these are: `uint8_t`, `int8_t`, etc.
+
+#### Avoid `using namespace` Statements in Headers
+
+By doing this, you are effectively forcing every other module that includes the
+header to also be using the namespace. This causes namespace pollution and
+generally defeats the purposes of namespaces. Fully-qualified symbols should be
+used instead.
+
+#### Classes / objects not exposed in a header should be in an anonymous namespace
+
+If a cpp class defines a class or instantiates a static object, it should be
+enclosed in an anonymous namespace.
+
+```
+namespace {
+  // CPP internal defines go here
+}  // namespace
+```
+
+#### Singleton use
+
+The decision to use a singleton class should be considered with care. Do not
+default to using a singleton for ease of writing code.
+
+If the class truly should be a singleton (ex. if it is controlling access to a
+hardware resource)
+
+-   The standard function name for accessing an SDK singleton is GetInstance().
+-   Singleton classes should delete copy and move constructors
+
+#### Avoid Heap-based Resource Allocation and auto-resizing std containers
+
+Heap-based resource allocation should be avoided. This includes any container
+element in std that automatically re-sizes itself at runtime (ex. vector, string
+etc.) as these re-size operations are often large and can lead to memory
+exhaustion and fragmentation on embedded systems.
+
+##### Alternatives
+
+In either case, recommended resource allocation alternatives are:
+
+-   In-place allocation and initialization
+-   Pool-based allocators
+-   Platform-defined and -assigned allocators
+
+[CHIPMem.h](https://github.com/project-chip/connectedhomeip/blob/master/src/lib/support/CHIPMem.h)
+provides support for platform defined allocators.
+
+[Pool.h](https://github.com/project-chip/connectedhomeip/blob/master/src/lib/support/Pool.h)
+is the Matter SDK pool allocator implementation.
+
+#### Prefer CopySpanToMutableSpan over memcpy when using spans
+
+See
+[Span.h](https://github.com/project-chip/connectedhomeip/blob/master/src/lib/support/Span.h)
+
+#### Prefer std::optional to CHIP implementation in newer code
+
+The Matter SDK Optional.h was implemented when the Matter SDK was C++14, but
+newer code can use std::optional, which offers some benefits over the Matter SDK
+implementation (ex. std::optional is trivially destructible if the underlying
+type is also trivially destructible)
+
+### Python
+
+#### Type hints
+
+Use type hints on function definitions for public APIs.
+
+#### Docstrings
+
+Docstrings should be included for all public APIs.
+
+#### mypy
+
+The current python code does not yet pass mypy checks, but we are working
+towards this goal. The more compliant new code is to mypy, the better.