Skip to content

Commit 23f1a6b

Browse files
authored
Merge pull request #1 from rzr/phcoval/review/main
coding_standard.md: Minor typos, fixes
2 parents ea0e682 + 00c64fd commit 23f1a6b

File tree

1 file changed

+3
-3
lines changed

1 file changed

+3
-3
lines changed

coding_standard.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -518,7 +518,7 @@ There will be functions that will not return `sl_status_t`. For example, functio
518518

519519
In any case, the following requirements must be complied with:
520520

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.
522522
- `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.
523523

524524
__Example__
@@ -1425,7 +1425,7 @@ __Example__
14251425

14261426
#### 4.6.4.5 Functions/stubs called on specific events/callbacks should start 'on' in their name (Required) ####
14271427

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.
14291429

14301430
__Example__
14311431
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
16161616

16171617
## 5.2 Comments should answer the question "Why?" (Required) ##
16181618

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).
16201620

16211621
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.
16221622

0 commit comments

Comments
 (0)