crash_course.md

Crash Course on SW Development:

Git, CI/CD, CAN, Compilation. Scary.
Relax. You'll be fine. This is in no particular order because there wasn't a cohesive flow. Generally Clean Code and Git are most important to understand early on.

Git:

Git is decentralized source control that has dominated the software industry for years now. It allows multiple parties to work on the same content simultaneously and then bring that work back together. Do not attempt to use it for Simulink files, only hand code. The project hinges on it. It will stretch your brain a bit but once you get it, you'll fall in love.

This course on youtube is pretty comprehensive and addresses a lot of pitfalls for newbies. At the very least it give the terminology to allow you to google yourself out of holes later. Even without a remote server, you can use git locally for any handcode.

You will need a github account and SBM will need to allow contributions from your account.

Tips: Commit early and often
Branch when you're not sure, it costs you nothing
Use pull requests to get buy-in from the team and document discussions.
Ask me for help on slack if you need it.
If you want to visualize the git graph without a GUI, use git log --graph --oneline --all --decorate.

I think it's worth noting that Github is just a company hosting git remote servers. They don't own the sw package git. More detail on GitHub Here

Mono-Repo

Just like it sounds: ONE REPO. A mono-repo is a concept used to help align SW dependencies between various components in a project. Git has means of sharing code between repositories (submodules) but they are cumbersome and a bit much for SW newbies.
The biggest shared dependencies in any project involving software and hardware are typically communication related which is defined by the .dbc file. Using a mono-repo structure removes any issues caused by different versions being used by two parties. The correct version exists in the repository at that commit and nowhere else.

CI/CD - Continuous Integration / Continuous Deployment

This is a big fancy word for "I automatically run tasks on someone else's computer". In the context of CI/CD typically that means building, testing, deploying, releasing etc. Github provides some basic functionality for this via Github Actions which we use for automating the creation of CAN .c and .h files, as discussed here. This removes managing a tool and process from your head. Just commit and push and the dependent code updates. Sketch files are also built on every push and required to to pass compilation checks on pull requests.

Clean Code - Critical

While you are 'passing through' Baja temporarily, you should write your code with the expectation that it can continue to be used after you are gone. This will happen in your career as well so it's good to get into the habit of coding as if you'll be handing it off to someone else. For the sake of the team and for the sake of your own growth, you should write code that allows someone to easily understand what the code is doing.

Career Pro-tip: Writing obtuse code is not job security, it's capping your own potential. If nobody can understand what you code is doing, nobody else can fix it but you and mental focus becomes hard to find as people continue to come to you for help.
Here are some pointers. We're in C/C++ but this is relevant to other content such as matlab and python.

Write Expressive Code

• Well written code needs a minimum of documentation in the form of comments.
• Use descriptive names. Even if it's a little long. Abbreviate only where it's obvious.
  • velocity_mps instead of v. We attach units in industry to variable names where applicable so there is no mistaking what the value represents.
  • calculatePathCurvature(float leftWhlSpd, float rightWhlSpd) instead of curv(float A,float B) for functions.
• If you verbally read the line of code out loud you should have a good idea of what's happening.

Be consistent across the repository

• Use the same terminology for concepts in variable names across the repo. Sounds a little abstract.
  • Example: I've seen lookup_table,mapping,linear_interp_function all end up pointing to the same idea. It causes useless confusion.
• Code styling across the repository. Longtin is right about the visual side of your brain being able to pick up things fast.
  • Use a consistent format for your sketch files and it will help you find bugs faster.
  • Indenting (Not up to us in python, I guess)
  • Bracket locations.
    • Are they after the if condition or on the next line?
• Type Case should be consistent. It's better if their application infers meaning.
  • With a single glance you know what a variable is.
  • Example from past career experience to demonstrate.
    • Class names: TitleCase
    • Private member variables: m_prefix_on_lowercase_with_underscore. Example: m_system_status
    • Local variable names: lowercase_with_underscore
    • Standalone Functions: lowercase_with_underscore

Don't do things that are hard to follow because 'it's clever'

• Don't be trying to do something in the minimum number of lines of codes.
• Nobody cares. The compiler optimizes way better than we think we do anyway.
• Don't increment/decrement a variable with in the middle of an operation because you can.
• If you have to do something that is obtuse because the naming can't easily describe, then add a code comment. But add a minimum of them because they tend to not get updated.

Don't repeat yourself

• If you're doing something repeatedly, break it out into a separate function.
• If all boards have the same operation being done on something, make that into a library that can be refined and tested and documented.

Unit tests

• I'm putting this at the bottom because it's difficult to be testing your content without a vehicle but in a real automotive SW project, there's a massive effort in testing.
• If any shared libraries get made for the team, we'll figure out how to test those.

Compilation Errors:

Literally copy them into google and try the first 3 things it gives you. Make a git branch for every attempt and throw it away if it doesn't work. That's how millions of people are making money every single day.