Document conventions pseudo-static-classes in design guideline

[pan-]

It is better to use a namespace than a class to group related free functions that do not belong into an object. Such constructs already exist in the codebase (see the namespace Kernel or ThisThread) however coding conventions for these programming elements are not well defined. It would be nice to have an entry in the design guideline that explains what these entities are and how they must be coded.

See discussion: 1, 2

[ciarmcom]

Internal Jira reference: https://jira.arm.com/browse/IOTDOCS-750

[iriark01]

@pan- we have a new edit of the contribution guidelines happening now on Development; do you want to add anything to that?

[AnotherButler]

We also have an API references for ThisThread and Kernel interface functions: https://os.mbed.com/docs/mbed-os/v5.13/apis/thisthread.html and https://os.mbed.com/docs/mbed-os/v5.13/apis/kernel-interface-functions.html

Does this address this issue?

[kjbracey]

I think @pan- was looking at an entry mentioning the design pattern for the coding guidelines. Maybe something like this for style.md:

Naming conventions

Classes

Functions

Namespaces

Namespaces used to group subsystems are lower-case, such as rtos and event. If not in a specific subsystem, C++ APIs are in namespace mbed. A few APIs remain in the global namespace for backwards compatibility.

Occasionally namespaces are used to act as-if "static singleton" objects. For example, namespace ThisThread in rtos (which was modelled after C++11 std::this_thread). These namespaces follow the class naming convention so that calls to their functions look like calls to static class methods. Typical namespace use in a source file:

using namespace rtos;

ThisThread::sleep_for(1000);

[AnotherButler]

We have added the content from @kjbracey-arm to our published documentation (PR linked above). Please feel free to reopen if you feel this has not been resolved.