You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: coding_standard.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -518,7 +518,7 @@ There will be functions that will not return `sl_status_t`. For example, functio
518
518
519
519
In any case, the following requirements must be complied with:
520
520
521
-
- if a function can fail, there must be a clear indication as to how to detect a failure. This is preferrably done through returning `sl_status`, but having a special 'invalid' value returned in case of failure is also allowed. No matter how this is achieved, it must be documented in the doxygen function header.
521
+
- if a function can fail, there must be a clear indication as to how to detect a failure. This is preferably done through returning `sl_status`, but having a special 'invalid' value returned in case of failure is also allowed. No matter how this is achieved, it must be documented in the doxygen function header.
522
522
-`bool` must not be returned to indicate success or failure. `bool` should only be used to indicate if a given condition is true or false. Even then, using an `enum` should be considered for future-proofing the function, should it need to return more than a true/false value in the future.
523
523
524
524
__Example__
@@ -1425,7 +1425,7 @@ __Example__
1425
1425
1426
1426
#### 4.6.4.5 Functions/stubs called on specific events/callbacks should start 'on' in their name (Required) ####
1427
1427
1428
-
Whenever a function is called to indicate an event occurred, or is called in 'reaction' to an event happenning, this function should have `on` in its name, directly after the `<module>_` prefix. This also applies to callbacks or function stubs shipped to the user.
1428
+
Whenever a function is called to indicate an event occurred, or is called in 'reaction' to an event happening, this function should have `on` in its name, directly after the `<module>_` prefix. This also applies to callbacks or function stubs shipped to the user.
1429
1429
1430
1430
__Example__
1431
1431
void sl_usb_on_device_connection(void);
@@ -1616,7 +1616,7 @@ Write documentation so that others can easily pick up the code. It makes life ea
1616
1616
1617
1617
## 5.2 Comments should answer the question "Why?" (Required) ##
1618
1618
1619
-
Write comments that say why the code is the way it is. What the code does, and how it does it, can usually be figured out from the code itself. Why it does it, and why it does it the way that it does, cannot. If you write it the bvious way, and it doesn't work, explain in a comment why it didn't. Otherwise the next person to come along is going to convert it back to the obvious method and have to learn the same painful lesson (or even worse, force you to relearn it).
1619
+
Write comments that say why the code is the way it is. What the code does, and how it does it, can usually be figured out from the code itself. Why it does it, and why it does it the way that it does, cannot. If you write it the obvious way, and it doesn't work, explain in a comment why it didn't. Otherwise the next person to come along is going to convert it back to the obvious method and have to learn the same painful lesson (or even worse, force you to relearn it).
1620
1620
1621
1621
There needs to be enough documentation that a peer can read and understand the code without having to ask the author for explanations. If a code reviewer feels the need to ask for explanations about how stuff works, then the code author should add this additional information as comments in the code.
0 commit comments