coding: Update coding guidelines

[agkaminski]

JIRA: RTOS-490

@anglov @nalajcie I am open to critique and suggestions. Have I forgot something?

[nalajcie]

H, many thanks for the docs update. I've pointed out some small typos (we really need spelling and markdown linting GA here!). As for the contents:

• I would highlight that we're using C99 standard as a base
• regarding the local variables in kernel - I think we should straighten the "according to C89 standard" (it says that the variables need to be declared at the beginning of each of the compound statement - so after each {) - either dropping the C89 standard or allowing declaring variables in function sub-scopes
• somewhere near limiting the scope of the variable I would advice also not to reuse variables for different purposes across the function
• not sure if this should be a rule but I would write that the variables (especially of complex types) need to be fully initialized before being used (or re-used in case of custom allocators) - partial initialization is not allowed (eg. partial msg_t initialization might lead to ugly inconsistent errors). For complex not zero-initialized variables I would advice using designated initializers

[anglov]

Additional remark, not covered with the changes:

About function names:
in terms of (non-standard) libraries, additional unique prefix should be used to avoid symbol colision
In our corelibs I can type one example of not unique and not obvious prefix: in libgraph header soft.h contains prefix soft_
soft can meaning many things and name conflict can be provoked accidentally

[agkaminski]

@anglov I think this rule is presented in Function names chapter

[anglov]

@anglov I think this rule is presented in Function names chapter

Yep, I write about things not covered by this chapter.

In general - it's common good practise to have unique prefixes inside non-standard libraries in C. In C++ this things are covered by namespaces, in C we only can rely on function names.

I believe that rule in coding standard is good for application code. For non-standard libraries it should be like:

[_]<library_prefix>_<subsystem>_<functionality>
or
[_]<library_prefix>_<functionality> when it's simple library or it's good to not have functionality prefix (eg. in main module)

Library prefix should be unique, and traceable.

I know that it's suggestion of kinda new rule but I believe not including it will cause a major problems sooner or later.

(btw. - for future consideration is using _ as prefix is also controvelsial with C/POSIX)

[agkaminski]

@anglov So, I added a rule about libraries with submodules, but I don't think I like it tbh.
How about instead of int foo_bar_start(void) make int foo_barStart(void)?
There're examples of both of these styles (+ many examples of no lib prefix at all), so we're free to choose.

[anglov]

@agkaminski well, to be honest the most important is to create that rule and use it consistently.

Personally I like the version with foo_bar_someNeatFunction (at least as a option) as it allows to split large libs to modules with separate visible namespace, similar as in apps.

But if you think that it's too much in naming, then I will be ok with common approach with one prefix across the lib.

[github-actions]

[markdownlint] _{reported by reviewdog 🐶}
MD013/line-length Line length [Expected: 120; Actual: 413]

[github-actions]

[markdownlint] _{reported by reviewdog 🐶}
MD013/line-length Line length [Expected: 120; Actual: 145]

[anglov]

I'm more than happy with current version