Coding Documentation¶
Code Style Standard¶
The following rules guide the production of code for Scout projects. The document is lengthy, but its motivating principles are simple. If you are new to the project, just read the summary and glance through the rules, so you know what's there for reference. While all rules are advisable, some are especially important for readability, and these are referenced in the summary. The more verbose specific rules serve primarily to resolve ambiguities and condemn specific pathological code styles observed in the past. The guidelines are written with C and C++ in mind, but the general principles and many of the specific rules are applicable to other languages as well.
If you do not understand one of the language concepts referenced herein, ask a senior member. We'd rather help you write good code now than fix it ourselves later.
TODO¶
- Add rules for language constructs specific to C++
- Add rules for Python
- Add doxygen standards
tl;dr¶
- Code is read once and written many times (attribution unknown but I think famous)
- If you can work harder writing your code to make it easier to understand, do it, because you will save your readers even more work
- Readable code favors simplicity, regularity, and structure that follows its meaning
- Make use of whitespace to break up code into manageable chunks
- Your code should be commented so as to allow easy reader comprehension
- But it should not be overly commented to provide information already obvious from reading the code
- Give things names that will mean the right thing to a reader unfamiliar with your code
- Use language provided constructs or established conventions for conveying meaning instead of inventing your own probably not-as-good mechanism
- You should read, understand, and follow without error the rules about function and variable naming, comments, parentheses and braces, and line breaks
- But seriously, read the whole thing sometime. It will make you work more effectively and efficiently, and other people that read your code will like you better.
- For types of formatting not addressed herein, maintain consistency within the code you are working on
File Organization¶
This will become more defined as the project progresses, but clear distinction should be made between code for the AVR and code for the ARM.- AVR code library should be relatively stable with few changes
- Largely ported from Colony dragonfly lib
- ARM library will be more dynamic and contain the projects and other low-level helper functions
- Generally, all language constructs that end up being memory-resident should be in C files, and all language constructs that do not end up being memory-resident should be in header files
- e.g. global variable declarations and function definitions should be in C files; function declarations, macro definitions, and type definitions should be in header files
- Exception: function declarations and type definitions properly declared
staticshould be in the C files to which they belong - Exception: function-like macros, if absolutely necessary and only used in one C file, should be defined in that C file
- Code for one project should be grouped into different files as appropriate to the project's decomposition into subunits
Version-Control Usage Guidelines¶
- Github has an excellent
Git tutorialadvertisement for Git - The gittutorial manual page is a straightforward introduction to the commands of Git and their uses
- Commit your changes whenever you make a significant change that works or at least works better than it used to
- Commit messages should have a suitably summarizing subject line and thoroughly describe all changes in the body
- Don't go into painful detail, but make sure readers know what the important differences are between the code before and after your commit
- If you fix a bug, say what the bad behavior was, what caused it, and what you did to fix it
- Someone who has read the commit message should be able to quickly scan the diff and not be surprised by what they see
- Lines of text in commit messages should not exceed 80 characters
- Do not commit binary files or files otherwise generated by a machine-specific build process
- In general, if there is any building to do, everybody should do their own building
- When modifying a file, do not back it up in another file and commit that file in case you need the old version later
- That's the exact scenario version control is designed to prevent
- Always commit any local changes before you pull from the master repository
- Always pull from the master repository, resolve and conflicts, and commit any local changes before you push to the master repository
- Never commit code that causes any existing build process to fail
- Never push any code that you know to causes a significant problem with something that used to work (or work better than it does now for you)
- If you make any new files that your code needs to build and run correctly, make sure you add them to repository and commit them
- Do not commit any files that are useless to other people
- e.g. editor backup files, test output files, throwaway code, the aforementioned backup files
- In general,
git add *is a bad idea
- When you commit, make sure that the list of changes matches what you had in mind
- Do not push changes you don't understand
- Do not use source code or random files as a channel for inter-developer communication about the project or status of the code
- That's what commit messages are for
ROS Installation Instructions¶
See http://www.ros.org/wiki/ROS/Installation for OS specific instructions
Gentoo-specific addendum:¶
- Building rxtools (and some other ROS packages ultimately depending on wxWidgets) might fail with the message, "Could NOT find wxWidgets." During ROS installation, the Gentoo package x11-libs/wxGTK will be installed to provide this service.
- The default system wxWidgets profile is none, even after you've installed wxGTK, which means wxWidgets is unusable by ROS as installed. You need to set the profile by running '
eselect wxwidgets gtk2-unicode-release-2.8'.- It may be possible to use a different profile than this. The only confirmed failure condition is when the profile is unset.
- After that, previously broken ROS packages should build without errors.
Miscellaneous Tips¶
- Ask senior members how to configure your text editor and version control software to automatically follow the rules for you
- If in doubt, ask before pushing to the master repository
- If your local repository seems broken, get someone to help you fix it sooner rather than later. It will only get harder as you diverge more and more from the master repository.
- If this guide is ambiguous, ask a senior member for clarification.
- Try not to sweat the small stuff. If you can stick to the most important parts of this guide and at least behave consistently in the other areas, you are already a better developer and nicer person than most of your peers.
Git hooks and a little trick for copyright info¶
- Sick of having to scroll through the Colony copyright header every time? So am I.
- Warning: This is not for people who are inexperienced with git! Some fairly dangerous stuff is below.
- I wrote a python script to remove all the copyright headers, and add them back.
- It's a file below: copyrightme.py.
- You can run it with "python copyrightme.py del", which replaces all headers with a short notice. "python copyrightme.py add" puts them back.
- I've tested this and it's fine for me, but if it has a bug that screws you over I'm sincerely sorry at best.
- I wrote a git pre-commit hook to stop myself from checking in files without copyright info, too.
- It's also below: pre-commit.
- Put it in your .git/hooks/ folder to use. Unlike the above, there should be no risks from this one.