404
Page not found :(
The requested page could not be found.
Page not found :(
The requested page could not be found.
Page not found :(
The requested page could not be found.
Maintained by Raghav Pillai
As an open source project, Navigator is always evolving and improving. We open our arms to anyone who’d like to contribute. To help guide contributors, we’ve developed detailed Code Guidelines & Standards, as well as documentation and branching guidelines that allow us to have a consistent developer experience regardless of author. This revolves around three main philosophies:
By following these guidelines, we can fulfill these philosophies, which allow us to have the most efficient developer experience possible, along with having a mature and maintainable codebase.
We will maintain both a main branch and a dev branch. main is more stable than dev. When you begin work on a feature or a bugfix, fork the dev branch, implement your change, and create a pull request back to dev once the change is relatively stable and well tested.
Start branch names with ‘feature_’, but other than that, name them however you want. Make the name descriptive and helpful. Don’t name a branch feature_zcc - that name is not helpful to someone trying to understand what the branch is for. However, feature_zed_camera_color clearly describes what the branch is for.
Make sure your commits are meaningful and grouped up. Don’t commit your entire change history into a single commit, group them up so you have a timeline of your progress.
When we are preparing for a release, we will create a branch off of dev to test and and add bugfixes. This release will start with release_ and end with a version number - for example, release_1_0. This allows us to continue merging features into dev while a release is being worked on. Once testing is complete, the release branch will be merged into both main and dev, so that the fixes applied during testing are applied everywhere. The commit in main will be tagged as our new release.
A cornerstone of good code is maintainability, which relies on understandable documentation. Navigator uses Doxygen to automatically generate high-level documentation from our user-defined documentation. Further documentation on how this works can be found below:
https://doxygen.nl/manual/docblocks.html
You can also use the VSCode Doxygen Generator to automatically generate proper documentation templates.
Below are the different types of documentation that are required for new contributions for Navigator.
Each file should have documentation on what the file accomplishes, as well as basic usage information. Below is our sample header comment template.
/*
* Package: package_name
* Filename: FileName.cpp
* Author: John Doe
@@ -49,4 +49,4 @@
Code standards and guidelines are a set of rules and best practices that help us create cleaner, readable and more maintainable code with minimal errors. This help us keep a cleaner, more consistent codebase. This helps us guarantee better code quality, lower code complexity and make more meaningful contributions over time. This all comes down to having better maintainability over time as we scale up our project.
Prefer readability over performance in most code. The obvious exception to this is code that is going to process a large amount of data (ie, the inner loop of a downsampler). However, much of our code runs relatively infrequently, so small performance gains are not worth obfuscating our code.
As our stack mainly contains C++ and Python code, we chose two styling guidelines for such, these being Google’s C++ guidelines for C++, and PEP 8 for Python. We heavily recommend you read at least an overview of these two guidelines. The main takeways for such are below:
Variables should be named in snake_case, and should be as verbose as possible. This allows for inherent readability. Examples of this are as below:
Names should be meaningful, even if it makes them very long. Good names are the #1 factor in writing readable code! Do NOT write int inchs = read(sa, b, BUFSZ); - instead write int characters_read = read(socket, buffer, buffer_size)
Abstract as much as possible! This helps with general code cleanliness and readability.
Live by the DRY philisophy - Don’t Repeat Yourself (“Every piece of knowledge must have a single, unambiguous, authoritative representation within a system”). This means reducing repetition of patterns and code duplication, and avoiding code redundancy and duplication.
Especially in Python, we want to make sure we use specific types. This helps us catch more error while building instead of during runtime, makes it easier to understand what a piece of code does through inherant code readability, and makes it easier for us to maintain! For example, we don’t want to use auto in C++, as this makes it difficult to infer what the variable actually does, instead specifically define the type. An example in Python of typing and type hinting can be found below.
def func(foo: int, bar: str) -> List:
ques: str = str(foo)
return [ques,bar]
-All constants and parameters should be moved out of the file, or on the top of files. This allows us to define constants at the highest possible level, and allow better readability. If constants require redefining at any point, they’ll need to be moved into the root param.yaml file. If not, put them at the top of the file, styled in accordance to our styling guidelines.