Coding Standard #240

bartekpaczek · 2025-11-03T09:38:49Z

Coding guide is converted to Coding Standard with additional rules added to comply with MISRA C rules.

github-actions

Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit

markdownlint

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

phoenix-rtos-doc/coding/misracprofile.md

Line 108 in 4df18e1

    
           | Rule 11.3 | Required | DISABLED | NO | This rule is not applicable for the Phoenix-RTOS kernel source code, because casting between different types of pointers can not be avoided in the operating system implementation. |

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

phoenix-rtos-doc/coding/misracprofile.md

Line 111 in 4df18e1

    
           | Rule 11.6 | Required | DISABLED | NO | This rule is not applicable for the Phoenix-RTOS kernel source code, because casting between pointer to void and an arithmetic type can not be avoided inn the operating system implementation. |

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

phoenix-rtos-doc/coding/misracprofile.md

Line 185 in 4df18e1

    
           | Rule 21.1 | Required | DISABLED | NO | This rule is not applicable for Phoenix-RTOS kernel source code, because common identifiers are defined within its codebase. |

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

phoenix-rtos-doc/coding/misracprofile.md

Line 186 in 4df18e1

    
           | Rule 21.2 | Required | DISABLED | NO | This rule is not applicable for Phoenix-RTOS kernel source code, because common identifiers are defined within its codebase. |

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

phoenix-rtos-doc/coding/misracprofile.md

Line 189 in 4df18e1

    
           | Rule 21.5 | Required | DISABLED | NO | This rule is not applicable for the Phoenix-RTOS kernel source code, because <signal.h> is proprietary to its codebase and has defined behavior. |

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

phoenix-rtos-doc/coding/misracprofile.md

Line 194 in 4df18e1

    
           | Rule 21.10 | Required | DISABLED | NO | This rule is not applicable for the Phoenix-RTOS kernel source code, because date and time functions are proprietary to its codebase and has defined behavior.  |

nalajcie · 2025-11-03T10:01:28Z

We should probably enable siblings_only: true for rule MD024 (https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md024---multiple-headings-with-the-same-content), still multiple Example headings have invalid level (and will trigger this warning then - this is what we want)

github-actions

Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit

markdownlint

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

phoenix-rtos-doc/coding/misracprofile.md

Line 185 in 33ff070

    
           | Rule 21.1 | Required | DISABLED | NO | This rule is not applicable for Phoenix-RTOS kernel source code, because common identifiers are defined within its codebase. |

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

phoenix-rtos-doc/coding/misracprofile.md

Line 186 in 33ff070

    
           | Rule 21.2 | Required | DISABLED | NO | This rule is not applicable for Phoenix-RTOS kernel source code, because common identifiers are defined within its codebase. |

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

phoenix-rtos-doc/coding/misracprofile.md

Line 189 in 33ff070

    
           | Rule 21.5 | Required | DISABLED | NO | This rule is not applicable for the Phoenix-RTOS kernel source code, because <signal.h> is proprietary to its codebase and has defined behavior. |

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

phoenix-rtos-doc/coding/misracprofile.md

Line 194 in 33ff070

    
           | Rule 21.10 | Required | DISABLED | NO | This rule is not applicable for the Phoenix-RTOS kernel source code, because date and time functions are proprietary to its codebase and has defined behavior.  |

coding/index.md

julianuziemblo

English spelling/grammar/logical nitpicks

coding/index.md

github-actions

Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit

markdownlint

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Example"]

phoenix-rtos-doc/coding/index.md

Line 716 in 43c5a58

#### Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Example"]

phoenix-rtos-doc/coding/index.md

Line 728 in 43c5a58

#### Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### PS-CODE-069"]

phoenix-rtos-doc/coding/index.md

Line 751 in 43c5a58

### PS-CODE-069

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Example"]

phoenix-rtos-doc/coding/index.md

Line 755 in 43c5a58

#### Example

[markdownlint] _{reported by reviewdog 🐶}
MD024/no-duplicate-heading Multiple headings with the same content [Context: "#### Note"]

phoenix-rtos-doc/coding/index.md

Line 779 in 43c5a58

#### Note

JIRA: DO-01

coding/index.md

julianuziemblo · 2025-12-10T08:38:05Z

coding/index.md

+#### Note
+
+The use of preprocessing conditionals makes it harder to follow the code logic and can be used only
+if it is absolutely necessary.


Maybe we could provide an example when it could be used, like defining common functionality for different platforms or running code only in debug mode.

Can you provide complete list of such exceptions?

The example provided could be connected to the example for the next rule: having code for MMU and no-MMU architectures in the same codebase and conditionally compiling it when necessary - this way we maximize code reuse

coding/index.md

julianuziemblo · 2025-12-10T08:41:40Z

coding/index.md

+If disabled or dead code is present (it was necessary), preprocessor should be used accordingly:

 ```c
 releveantCode();

 #if 0
    obsoleteFunction();
 #endif
 ```


I was under the impression we didn't want code like this in the kernel as we removed such situations, relying on version control to keep replaced code accessible.

coding/index.md

julianuziemblo · 2025-12-10T09:05:43Z

coding/index.md

+It is not allowed to make an indentation with space character. The source code
 used for development tests (e.g. printf debug) should be entered without indentation. The following code presents
 correctly formatted code with one line (`lib_printf`) entered for debug purposes. The inserted line should be removed
 in the final code.


This clashes with the formatter used and is not used in the kernel or anywhere in the main codebase to my knowledge. I think this note and example should be removed @nalajcie @Darchiv

yeah, we should remove the not-indented debug messages - they should never appear in commited code anyway.

Please note that the example code currently breaks this rule (the debug code is indented) - in current coding convention it's written correctly, so I assume it's just a ^C^V error.

nalajcie · 2025-12-10T09:41:10Z

coding/index.md

@@ -1,14 +1,49 @@
-# Coding convention
+# Software Code Standards


this standard is only for C language, should we emphasize it somewhere? (it doesn't speak about eg. Assembler)

You are right, we are missing Assembler part. Can you point me to any resources I can use to formulate rules for Assembler?

not really, what I'm saying is that we should treat this document as C Software Coding Standard (as when you're writing in bash, make or some other lang used withing project (either code or configuration) - the rules to follow are not included in this document (and should not be - there should be separate document per language - together they create Software Code Standards)).

agkaminski · 2025-12-18T12:43:33Z

coding/index.md

+### PS-CODE-REC-007

-Labels in each file should be constructed according to presented rules. Modification of these rules is not allowed.
+Only characters from the standard ASCII range (0x20–0x7E) should be used in source files.


Turbo nit: what about new line etc? 😄

agkaminski · 2025-12-18T12:45:26Z

coding/index.md

+### PS-CODE-REC-012

-Functions should be short and not too complex in terms of logic. The function should do one thing only. Functions should
-be separated with two newline characters.
+The function should do one thing only.


Not really followed and not really practical rule, I vote against

If it was a rule yeah, but it's a recommendation - IMO valueable to have some form of it here

agkaminski · 2025-12-18T12:45:44Z

coding/index.md

-is the name of subsystem or file to which function belongs and `<functionality>` is the brief sentence explaining the
-implemented functionality. The subsystem name should be a one word without the underline characters. The functionality
-could be expressed using many words but without the underlines. In such case camelCase should be used.
+Functions should be separated with two `newline` characters.


2 empty lines instead of newline

kind of depends how specific we have to get with these rules. Maybe newlines is better for when someone uses Windows for development and pollutes the repo with CRLFs?

Good thinking, UNIX style new line should be enforced

agkaminski · 2025-12-18T12:48:02Z

coding/index.md

+#### Note
+
+An underscore character at the start of the function name indicates that the function is not synchronized, and its usage
+by two parallel threads requires external synchronization. A good example of such function is the internal function


Suggested change

by two parallel threads requires external synchronization. A good example of such function is the internal function

requires external synchronization. A good example of such function is the internal function

agkaminski · 2025-12-18T12:48:54Z

coding/index.md

+
+### PS-CODE-REC-020
+
+Functions exported outside the subsystem should be named with the subsystem name only.


We require such naming scheme anyway

agkaminski · 2025-12-18T13:02:32Z

coding/index.md

+
+### PS-CODE-REC-55
+
+The type specifiers from the list bellow should be used:


What about stdint?

This sounds like "don't write unsigned instead of unsigned int because this is our standard" - this should definetely be re-worded

maybe something like "If default C types are to be used, only use those from the list below"?

agkaminski · 2025-12-18T13:03:46Z

coding/index.md

+
+*Recommendation derived from MISRA C.*
+
+Types of defined length should be used over default C types.


This is in direct contradiction with PS-CODE-REC-55

I'd make this recommendation preceed PS-CODE-REC-55

agkaminski · 2025-12-18T13:04:00Z

coding/index.md

+
+### PS-CODE-REC-060
+
+`//` comments should not to be used.


agkaminski · 2025-12-18T13:05:11Z

coding/index.md

+#### Note
+
+Comments are not the place to express programmer's novel writing skills.


Let's tone down aggression while we're here

Suggested change

#### Note

Comments are not the place to express programmer's novel writing skills.

agkaminski · 2025-12-18T13:07:38Z

coding/index.md

+#### Explanation
+
+It’s not sufficient to mark them with `U` as MISRA classifies `U` constants, despite the C standard implications, as
+8-bit essential type (see the “To assist in understanding” example in Rule 12.2 rationale, D.3 and D.7.4).


We cannot assume that reader has an access to the closed norm.

If it would happen that we want to assume that, then exact document should be also specified (what if newer or older revision place the rule and directive on some other identifier?)

bartekpaczek requested a review from kber-ps November 3, 2025 09:38

github-actions bot reviewed Nov 3, 2025

View reviewed changes

coding/index.md Show resolved Hide resolved

julianuziemblo reviewed Nov 4, 2025

View reviewed changes

coding/index.md Show resolved Hide resolved

julianuziemblo reviewed Nov 4, 2025

View reviewed changes

github-actions bot reviewed Nov 7, 2025

View reviewed changes

bartekpaczek force-pushed the bpaczek/do178c branch from 5a555d6 to 0720e81 Compare November 7, 2025 11:50

CODESTD: Adding Coding Standard and MISRA profile

72eb79b

JIRA: DO-01

bartekpaczek force-pushed the bpaczek/do178c branch from 9066de6 to 72eb79b Compare November 14, 2025 15:44

bartekpaczek added 4 commits November 20, 2025 13:54

CODESTD: Implementing review comments

35b9fef

CODESTD: Add reviewer and revision history.

d704c45

CODESTD: Add latex if for doc Reviewer

0f4d0b1

CODESTD: Add dochistory if

d4729c4

julianuziemblo reviewed Dec 10, 2025

View reviewed changes

nalajcie reviewed Dec 10, 2025

View reviewed changes

CODESTD: Implement review comments

c8f9c89

bartekpaczek marked this pull request as ready for review December 15, 2025 07:57

agkaminski reviewed Dec 18, 2025

View reviewed changes

		@@ -1,14 +1,49 @@
		# Coding convention
		# Software Code Standards

	by two parallel threads requires external synchronization. A good example of such function is the internal function
	requires external synchronization. A good example of such function is the internal function


		### PS-CODE-REC-020

		Functions exported outside the subsystem should be named with the subsystem name only.


		### PS-CODE-REC-55

		The type specifiers from the list bellow should be used:


		Recommendation derived from MISRA C.

		Types of defined length should be used over default C types.

		#### Note

		Comments are not the place to express programmer's novel writing skills.

Coding Standard #240

Are you sure you want to change the base?

Coding Standard #240

Uh oh!

Conversation

bartekpaczek commented Nov 3, 2025

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Uh oh!

nalajcie commented Nov 3, 2025

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

julianuziemblo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!