Skip to content

Commit 75771b1

Browse files
authored
Docs minor spelling and section fixes (UBC-Thunderbots#3497)
* Docs update code-style-guide remove repeated section * Docs fix typos
1 parent 45a6f3a commit 75771b1

3 files changed

Lines changed: 6 additions & 22 deletions

File tree

docs/code-style-guide.md

Lines changed: 2 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ If you want to know more about our coding style you can take a look at our [clan
4444
* All variable names are `lowercase_with_underscores`
4545
```cpp
4646
// Incorrect
47-
float calculatedDistnace;
47+
float calculatedDistance;
4848

4949
// Correct
5050
float calculated_distance;
@@ -179,7 +179,7 @@ If you think some ASCII art will help explain something better, go for it! [asci
179179
180180
### Includes
181181
182-
* Use `#include` sparingly and only include the necessary sources to build the file. Do not include headers whos class or implementation is not used.
182+
* Use `#include` sparingly and only include the necessary sources to build the file. Do not include headers whose class or implementation is not used.
183183
* Often `.cpp` files include its corresponding header `.h` file, it means the `.cpp` file include everything included in the header. Do not have duplicate `#include`'s in both `.h` and `.cpp` files.
184184
* `#include`s are generally preferred written on the `.cpp` side; use minimum `#include` in the header file. Use _forward declarations_ in headers if necessary.
185185
* Specify full path of the include file on the file system, relative to the top-level project directory or _WORKSPACE_ file. Do not use relative paths.
@@ -273,22 +273,6 @@ private functions for a class/file that should not be exposed to users. impl can
273273
// Correct
274274
using PointsArray = std::vector<std::pair<int, int>>;
275275
```
276-
* Avoid initializing multiple variables on the same line.
277-
```cpp
278-
// Incorrect
279-
int x, y, z = 0;
280-
281-
// Correct
282-
int x;
283-
int y;
284-
int z = 0;
285-
286-
// However, the author may have intended the following
287-
// or a code reader may have assumed the following
288-
int x = 0;
289-
int y = 0;
290-
int z = 0;
291-
```
292276
* Avoid ternary operators. Clarity is more important than line count.
293277
```cpp
294278
// Incorrect

docs/coroutine_test_examples.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -505,7 +505,7 @@ int main(int argc, char** argv)
505505
//
506506
// The move constructor / assgnment is allowed.
507507
//
508-
// We can verify this with the code below, or by lookinAg at pull_coroutine.hpp
508+
// We can verify this with the code below, or by looking at pull_coroutine.hpp
509509
// https://www.boost.org/doc/libs/1_74_0/libs/coroutine2/doc/html/coroutine2/coroutine/asymmetric/pull_coro.html
510510

511511
auto data = std::make_shared<int>(99);

docs/software-architecture-and-design.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -521,7 +521,7 @@ Once it is time to start the pass, the condition for the loop will become false
521521
Once we have entered the second stage, we know we don't have to look at the first stage again. Because the coroutine "remembers" where the execution is each time the function is called, we will resume inside the second stage and therefore never execute the first stage again! This makes it much easier to write and read this strategy code, because we can clearly see the 2 stages of the strategy, and we know they will be executed in order.
522522

523523
### Coroutine Best Practices
524-
Coroutines are a complex feature, and the boost coroutines we use don't always behave in was we expect. We have done extensive testing on how coroutines are safe (or not safe) to us, and derived some best practices from these examples. See [coroutine_test_exmaples.cpp](coroutine_test_examples.cpp) for the full code and more detailed explanantions.
524+
Coroutines are a complex feature, and the boost coroutines we use don't always behave in was we expect. We have done extensive testing on how coroutines are safe (or not safe) to us, and derived some best practices from these examples. See [coroutine_test_examples.cpp](coroutine_test_examples.cpp) for the full code and more detailed explanantions.
525525

526526
To summarize, the best practices are as follows:
527527
1. Avoid moving coroutines. If the absolutely must be moved, make sure they are not moved between the stack and heap.
@@ -619,7 +619,7 @@ Our simulator is what we use for physics simulation to do testing when we don't
619619
* [SSL-Vision](#ssl-vision) by publishing new vision data
620620
* the robots by accepting new [Primitives](#primitives)
621621

622-
Using the current state of the simulated world, the simulator simulates the new [Primitives](#primitives) over some time step and publishes new SSL vision data based on the updated simulated world. Since the simulator interfaces with the our software over the network, it is essentially indistinguishible from robots receiving [Primitives](#primitives) and an [SSL-Vision](#ssl-vision) client publishing data over the network.
622+
Using the current state of the simulated world, the simulator simulates the new [Primitives](#primitives) over some time step and publishes new SSL vision data based on the updated simulated world. Since the simulator interfaces with the our software over the network, it is essentially indistinguishable from robots receiving [Primitives](#primitives) and an [SSL-Vision](#ssl-vision) client publishing data over the network.
623623

624624
The simulation can also be configured with "realism" parameters that control the amount of noise added to vision detections, simulate missed vision detections and packet loss, and add artificial vision/processing delay, all with some degree of randomness.
625625

@@ -652,7 +652,7 @@ A `Validation Function` comes in two types:
652652
2. Non-terminating: Some condition that must be met for the entire duration of the test, i.e. "for all time". (*Eg. The ball never leaves the field or all friendly robots follows SSL rules*).
653653

654654
Benefits of `Validation Functions`:
655-
1. They are reuseable. We can write a function that validates the ball never leaves the field, and use it for multiple tests.
655+
1. They are reusable. We can write a function that validates the ball never leaves the field, and use it for multiple tests.
656656
2. They can represent assertions for more complex behaviour. For example, we can build up simpler `Validation Functions` until we have a single `Validation` function for a specific [Tactic](#tactics).
657657
3. They let us validate independent sequences of behaviour. For example, we create a different `ValidationFunction` for each [Robot](#robot) in the test. This makes it easy to validate each [Robot](#robot) is doing the right thing, regardless if they are dependent or independent actions.
658658

0 commit comments

Comments
 (0)