drinkingtea/nostalgia
drinkingtea/nostalgia
2
0
Fork 0
Code Issues 6 Pull Requests Actions Releases 6 Activity

[nostaliga] Update Developer Handbook paragraph formating to one sentence/line

Browse Source
This commit is contained in:
Gary Talent 2021-07-17 18:16:32 -05:00
parent 0420dfb545
commit dce98590fc
1 changed files with 46 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
developer-handbook.md
View File

@ -2,12 +2,13 @@
## About ## About
The purpose of the Developer Handbook is similar to that of the README. The The purpose of the Developer Handbook is similar to that of the README.
README should be viewed as a prerequisite to the Developer Handbook. The README The README should be viewed as a prerequisite to the Developer Handbook.
should provide information needed to build the project, which might be used by The README should provide information needed to build the project, which might
an advanced user or a person trying to build and package the project. The be used by an advanced user or a person trying to build and package the
Developer Handbook should focus on information needed by a developer working on project.
the project. The Developer Handbook should focus on information needed by a developer
working on the project.
## Project Structure ## Project Structure
@ -65,14 +66,16 @@ The C++ language designers aren't stupid. Question them, but don't ignore them.
#### Casting #### Casting
Do not use C-style casts. C++ casts are more readable, and more explicit about Do not use C-style casts.
the type of cast being used. Do not use ```dynamic_cast``` in code building for the C++ casts are more readable, and more explicit about the type of cast being
GBA, as RTTI is disabled in GBA builds. used.
Do not use ```dynamic_cast``` in code building for the GBA, as RTTI is disabled
in GBA builds.
#### Library Usage #### Library Usage
C++ libraries should generally be preferred to C libraries. C libraries are C++ libraries should generally be preferred to C libraries.
allowed, but pay extra attention. C libraries are allowed, but pay extra attention.
This example from nostalgia::core demonstrates the type of problems that can This example from nostalgia::core demonstrates the type of problems that can
arise from idiomatically mixed code. arise from idiomatically mixed code.
@ -115,37 +118,41 @@ int main() {
The code base where this was observed actually got away with this for the most The code base where this was observed actually got away with this for the most
part, as the std::vector implementation used evidently waited until the part, as the std::vector implementation used evidently waited until the
internal array was needed before initializing and the memory was zeroed out internal array was needed before initializing and the memory was zeroed out
because the allocation occurred early in the program's execution. While the because the allocation occurred early in the program's execution.
std::vector implementation in question worked with this code and the memory leak While the std::vector implementation in question worked with this code and the
is not noticeable because the std::vector was meant to exist for the entire life memory leak is not noticeable because the std::vector was meant to exist for
of the process, other classes likely will not get away with it due to more the entire life of the process, other classes likely will not get away with it
substantial constructors and more frequent instantiations of the classes in due to more substantial constructors and more frequent instantiations of the
question. classes in question.
### Pointers vs References ### Pointers vs References
Pointers are generally preferred to references. References should be used for Pointers are generally preferred to references. References should be used for
optimizing the passing in of parameters and for returning from accessor optimizing the passing in of parameters and for returning from accessor
operators (e.g. ```T &Vector::operator[](size_t)```). As parameters, references operators (e.g. ```T &Vector::operator[](size_t)```).
should always be const. A non-const reference is generally used because the As parameters, references should always be const.
parameter value is changed in the function, but it will look like it was passed A non-const reference is generally used because the parameter value is changed
in by value where it is called and thus not subject to change. The reference in the function, but it will look like it was passed in by value where it is
operator makes it clear that the value can and likely will change. called and thus not subject to change.
The reference operator makes it clear that the value can and likely will change.
### Error Handling ### Error Handling
Exceptions are clean and nice and gleefully encouraged in userland code running Exceptions are clean and nice and gleefully encouraged in userland code running
in environments with expansive system resources, but absolutely unacceptable in in environments with expansive system resources, but absolutely unacceptable in
code running in restrictive bare metal environments. The GBA build has them code running in restrictive bare metal environments.
disabled. Exceptions cause the compiler to generate a great deal of extra code The GBA build has them disabled.
that inflates the size of the binary. The binary size bloat is often cited as Exceptions cause the compiler to generate a great deal of extra code that
one of the main reasons why many embedded developers prefer C to C++. inflates the size of the binary.
The binary size bloat is often cited as one of the main reasons why many
embedded developers prefer C to C++.
Instead of throwing exceptions, all engine code must return error codes. Instead of throwing exceptions, all engine code must return error codes.
Nostalgia and Ox both use ```ox::Error``` to report errors. ```ox::Error``` is Nostalgia and Ox both use ```ox::Error``` to report errors. ```ox::Error``` is
a struct that has overloaded operators to behave like an integer error code, a struct that has overloaded operators to behave like an integer error code,
plus some extra fields to enhance debuggability. If instantiated through the plus some extra fields to enhance debuggability.
```OxError(x)``` macro, it will also include the file and line of the error. If instantiated through the ```OxError(x)``` macro, it will also include the
file and line of the error.
The ```OxError(x)``` macro should only be used for the initial instantiation of The ```OxError(x)``` macro should only be used for the initial instantiation of
an ```ox::Error```. an ```ox::Error```.
@ -192,18 +199,20 @@ Lastly, there are a few macros available to help in passing ```ox::Error```s
back up the call stack, ```oxReturnError```, ```oxThrowError```, back up the call stack, ```oxReturnError```, ```oxThrowError```,
```oxIgnoreError```, and ```oxRequire```. ```oxIgnoreError```, and ```oxRequire```.
```oxReturnError``` is by far the more helpful of the two. ```oxReturnError``` ```oxReturnError``` is by far the more helpful of the two.
will return an ```ox::Error``` if it is not 0 and ```oxThrowError``` will throw ```oxReturnError``` will return an ```ox::Error``` if it is not 0 and
an ```ox::Error``` if it is not 0. Because exceptions are disabled for GBA ```oxThrowError``` will throw an ```ox::Error``` if it is not 0.
builds and thus cannot be used in the engine, ```oxThrowError``` is only really Because exceptions are disabled for GBA builds and thus cannot be used in the
useful at the boundary between engine libraries and Nostalgia Studio. engine, ```oxThrowError``` is only really useful at the boundary between
engine libraries and Nostalgia Studio.
```oxIgnoreError``` does what it says, it ignores the error. Since ```oxIgnoreError``` does what it says, it ignores the error.
```ox::Error```s always nodiscard, you must do something with them. Since ```ox::Error```s always nodiscard, you must do something with them.
In extremely rare cases, you may not have anything you can do with them or you In extremely rare cases, you may not have anything you can do with them or you
may know the code will never fail in that particular instance. may know the code will never fail in that particular instance.
This should be used very sparingly. At the time of this writing, it has only This should be used very sparingly.
been used 4 times in 20,000 lines of code. At the time of this writing, it has only been used 4 times in 20,000 lines of
code.
```cpp ```cpp