Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
doc:guidelines [2015/04/28 15:27] – [Development of Roslisp Packages] gkazhoya | doc:guidelines [2019/07/11 13:24] (current) – gkazhoya | ||
---|---|---|---|
Line 7: | Line 7: | ||
* Always use the GIT version control system when developing | * Always use the GIT version control system when developing | ||
* One commit per feature with a meaningful commit message | * One commit per feature with a meaningful commit message | ||
+ | * Use square brackets to annotate for which package the commit is. E.g.: ''" | ||
* Send a //pull request// through GitHub, when: | * Send a //pull request// through GitHub, when: | ||
* you want somebody to review your code | * you want somebody to review your code | ||
Line 16: | Line 17: | ||
==== Development of Roslisp Packages ==== | ==== Development of Roslisp Packages ==== | ||
- | **package.xml/ | + | **package.xml** |
Relevant documentation: | Relevant documentation: | ||
- | | + | * As a ''< |
- | | + | |
* Use ''< | * Use ''< | ||
* The license for all CRAM code should be BSD / Public Domain | * The license for all CRAM code should be BSD / Public Domain | ||
Line 35: | Line 35: | ||
**Lisp** | **Lisp** | ||
- | * Pay attention to the indentation! | + | * Pay attention to the indentation!!! |
* Try not to exceed 80 symbols in width in your code | * Try not to exceed 80 symbols in width in your code | ||
- | * Lisp names (variables, classes, methods, packages) are all lowercase with dashes in between: my-awesome-lisp-variable | + | * Lisp names (variables, classes, methods, packages) are all lowercase with dashes in between: |
- | * Do you usually get that feeling that something is underdocumented? | + | * Do you usually get that feeling that something is underdocumented? |
+ | * Try not to '' | ||
+ | * Don't use '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
**Ros-related** | **Ros-related** | ||
- | * ROS packages' | + | * ROS packages' |
- | ==== Lisp Programming | + | ==== Copyright notices |
- | Some Lisp patterns and stuff would be nice, like tail recursive functions | + | CRAM is open source software licensed under the BSD licence. |
+ | This means the code can be used by any third party without having to contribute anything back and having to mention | ||
+ | Our copyright notice is there to allow others to use our software without being afraid of being sued. | ||
- | ==== Testing ==== | + | An example copyright notice can be found in the header of most '' |
- | The preferred Lisp package for writing simple unit tests is [[http:// | + | Here are some guidelines on how to deal with the copyright notice of your code: |
+ | * When you create a new '' | ||
+ | * If you simply copy pasted a file, please keep the original notice intact. | ||
+ | * For non-sourcecode files such as a '' | ||
+ | * When editing an existing file, you can add your name into the header if you made a substantial contribution to the code. | ||
- | **Running existing tests** | + | A contribution is considered substantial if: |
+ | | ||
+ | | ||
+ | | ||
- | Just do | + | A contribution is considered not substantial if: |
+ | * you fixed a typo, | ||
+ | * fixed indentation, | ||
+ | * slightly improved a documentation string, | ||
+ | * other minor contributions such as minor refactoring and nicification, | ||
+ | * minor bug fixes, | ||
+ | * copy paste of existing code with minor tweaks. | ||
- | < | + | This definition is, of course, not quantitative. If you are unsure, ask the current main maintainer of the software for an advice or look on the Internet for some inspiration, |
- | The asdf system for tests usually has either the '' | ||
- | And then: | + | ==== Unit Testing ==== |
- | <code> | + | Testing your code is essential! |
- | ,!p asdf-system-to-test-tests | + | CRAM is a huge framework with a thousands of lines of code, so we have to make sure that whatever bricks we put in our CRAM skyscraper, they are robust. A couple of fragile bricks and our whole building will collapse. |
- | (run-tests) | + | |
- | </ | + | |
- | or | + | |
- | < | + | |
- | ... | + | |
- | (run-tests my-define-tests-function-name) | + | |
- | </ | + | |
- | That's all. | + | To aid with testing, consider adding unit tests to functions in your code that have math and to your main API functions. |
+ | Take a look at the [[http:// | ||
- | **Writing unit tests for your functions** | ||
- | TODO: here should go a link with some testing tutorial | + | ==== Lisp Programming ==== |
+ | Todo: Some Lisp patterns and stuff would be nice, like tail recursive functions and optimization flags, making sure the functions have no side effects, etcetc... | ||
- | **FiveAM** | ||
- | If lisp-unit isn't expressive enough for you, consider using [[http:// | ||
- | To run tests written with FiveAM (1) load the tests asdf package, (2) change to the corresponding Lisp package in the REPL and (3) execute '' |