/dev-guidelines

Software and hardware development guidelines

dev-guidelines

Software and hardware development guidelines

Table of Contents

Software

One's profession should not be measured by the actions that are taken, but rather by the end-goal and the means of achieving such goal.

Anyone can program, not everyone can develop scalable, robust, and maintainable software. Let's aim for that...

You may find a list of useful books and resources here.

Styleguides

Documentation

Self describing, terse code should be the norm. But, often times the complexity ....

Dependency Management

Version Control

We use Git as our version control system (VCS) and GitHub as our open-source Git hosting service.
Below are some quick rules to follow when working with a version control system, specifically Git:

  1. Make sure the build succeeds before committing.
    Rationale: Broken code should not be committed.

  2. Create feature branches.
    Rationale: Changes to a branch don’t affect other developers on the team. This is a good thing because a feature under development can create instability.

  3. Pull down the latest changes before beginning to code.
    Rationale: Keep you local version up to date. This is crucial if you’re working on feature branch, don’t let your branch diverge too far from the master branch.

  4. Use meaningful and succinct git messages.
    Rationale: “A commit message shows whether a developer is a good collaborator”. A project’s long-term success rests (among other things) on its maintainability and being able to review others’ commits and pull requests with ease.
    This drives efficiency.

Git Messages

When committing code into a Git repository, you will have to write a message describing your code changes.
It is crucial that we make these messages concise and consistent. A well-crafted commit message can tell other developers right away why your code changes matter or why they took place.

Chris Beams has a great post that summarizes the importance of a well-crafted commit message, along with the rationale behind it. Below are the seven rules he writes in his post, check out his post for more information.

The seven rules of a great Git commit message

  1. Separate subject from body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why vs. how

Gitignore

What is .gitignore?

GitHub

Software Releases

Tools

Know your tools, from debuggers, to profilers, to IDEs.

IDEs

IntelliJ

Eclipse

Middleware and Frameworks

ROS

Hardware

Tools