bluerobotics/software-guidelines

Guidelines for software development, code style, communication etc.

Table of Contents

Guidelines

• Code
• Style
• Version Control
• Communication

Tools, Tips, and Tricks

• Compilers

software-guidelines's Issues

Version Control: improve "how" and document "why"

Some relevant discussion/thoughts in this PR.

Code style

From some discussion within the team, update guidelines/style.md to

• use a language's specific style if it has one (e.g. PEP8 for Python)
• stability is important - avoid style-based breaking API changes until there are breaking changes for other reasons

Add guideline about TODO inline with code.

bluerobotics/ping-viewer#419

guidelines/communication: Remove 'Hangouts' - Slack only now

Add style for expressions

Patrick likes no spaces for * or / operators, and space for everything else:
if ((_maxDepthToDraw - _minDepthToDraw)*_minPixelsPerMeter < 200) {

I like single space between every mathematical or logical operator:
if ((_maxDepthToDraw - _minDepthToDraw) * _minPixelsPerMeter < 200) {

Is this something we should add a guideline for? or just leave it to preference?

There is also the matter of a space after the if or while statements.

Add information about tag formats

Add explanation of why master branch is protected and push force should not happen

We did discussed that before and we ended up the current approach, minor changes can appear to be safe, but they may not be or could be done in a better way, so to avoid such problem and be sure that we are not doing something crazy, we agreed to have at least a single approved to any PR, more approves may be necessary if the change is complex or if you desire to have more eyes to be sure that the current approach is correct or may broken something that you are not aware.
We have master branch protected for the majority of our repositories.
PR's are really simple to do, and should not hold your workflow, you can open as much PRs that you feel like, or a single PR with a bunch of fixes. If you are waiting to merge something to add to the documentation before talking with an user, you can ping someone directly and we could approve asap.

I generally avoid committing directly to master, ever. Even a pr as simple as this one could break I forgot we are at Python 3.4 and tried to use f-strings in there.
while there is some extra work to it, these ones are pretty easy to do and quick to review.