Differences

This shows you the differences between two versions of the page.

Link to this comparison view

doc:guidelines [2019/02/14 19:27]
gkazhoya
doc:guidelines [2019/07/11 15:24] (current)
gkazhoya
Line 21: Line 21:
 Relevant documentation:​ [[http://​www.ros.org/​reps/​rep-0127.html|Package.xml Ref]] Relevant documentation:​ [[http://​www.ros.org/​reps/​rep-0127.html|Package.xml Ref]]
  
-  * As a ''<​build_depend>''​ only specify all the rosdep keys or ROS packages that your package requires at build-time, e.g. other ROS package sources, library headers. Whereas, ''<​run_depend>''​ is for rosdep keys and ROS packages that your package needs at run-time, e.g. shared libraries, executables,​ Python modules, launch scripts. \\ For example, you should put ''​sbcl''​ as a build dependency for all your Lisp packages. Although we don't explicitly use ''​sbcl''​ when ''​catkin_make''​-ing our Roslisp packages, you will still need ''​sbcl''​ in the next step of your compilation process (inside emacs slime). For all packages where ''​sbcl''​ is a build dep, it will be automatically ''​sudo apt-get install''​-ed by ''​rosdep''​ when you first cloned the source code of that package and ran ''​rosdep''​ on it. On the other hand, you actually don't need a Common Lisp compiler during the execution of your compiled Lisp ''​*.fasl''​ executives, so I guess you don't need ''​sbcl''​ as a run dep (is this actually correct?​)... A good example of this is: ''<​build_depend>​libsomelib1.6-dev</​build_depend>'',​ whereas ''<​run_depend>​libsomelib1.6</​run_depend>''​. More documentation for this can be found [[http://​wiki.ros.org/​catkin/​conceptual_overview#​Dependency_Management|here]].+  * As a ''<​build_depend>''​ only specify all the rosdep keys or ROS packages that your package requires at build-time, e.g. other ROS package sources, library headers. Whereas, ''<​run_depend>''​ is for rosdep keys and ROS packages that your package needs at run-time, e.g. shared libraries, executables,​ Python modules, launch scripts. More documentation for this can be found [[http://​wiki.ros.org/​catkin/​conceptual_overview#​Dependency_Management|here]].
   * Use ''<​export><​deprecated /></​export>''​ to tag deprecated packages   * Use ''<​export><​deprecated /></​export>''​ to tag deprecated packages
   * 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! ​:D+  * 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: ​''​my-awesome-lisp-variable''​
   * Do you usually get that feeling that something is underdocumented?​ :) Think about that when writing your own code. (not that the author of this guideline always sticks to this particular rule, unfortunately...)   * Do you usually get that feeling that something is underdocumented?​ :) Think about that when writing your own code. (not that the author of this guideline always sticks to this particular rule, unfortunately...)
   * Try not to ''​use''​ too many packages in your ''​package.lisp''​. Instead, specify package namespaces explicitly in your code, e.g. ''​cl-transforms:​x''​ instead of ''​x''​. That way code is more readable.   * Try not to ''​use''​ too many packages in your ''​package.lisp''​. Instead, specify package namespaces explicitly in your code, e.g. ''​cl-transforms:​x''​ instead of ''​x''​. That way code is more readable.
Line 48: Line 48:
 **Ros-related** **Ros-related**
  
-  * ROS packages'​ names are usually lowercase with underscores in between: my_awesome_ros_package+  * ROS packages'​ names are usually lowercase with underscores in between: ​''​my_awesome_ros_package''​. 
 + 
 + 
 +==== Copyright notices ==== 
 +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 the original authors. 
 +Our copyright notice is there to allow others to use our software without being afraid of being sued. 
 + 
 +An example copyright notice can be found in the header of most ''​*.lisp''​ files in CRAM. 
 + 
 +Here are some guidelines on how to deal with the copyright notice of your code: 
 +  * When you create a new ''​*.lisp''​ or ''​*.asd''​ file or any other source code file, please add a copyright notice with your name and institution name. 
 +  * If you simply copy pasted a file, please keep the original notice intact. 
 +  * For non-sourcecode files such as a ''​package.xml''​ file, make sure to simply put your name in the correct tag (e.g. ''<​author>''​). 
 +  * When editing an existing file, you can add your name into the header if you made a substantial contribution to the code. 
 + 
 +A contribution is considered substantial if: 
 +  * you added a new feature, 
 +  * you fixed a major bug and thereby edited many lines of code in the file, 
 +  * you made a major refactoring of the code and improved readability and maintainability greatly. 
 + 
 +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,​ e.g., from the [[https://​www.gnu.org/​prep/​maintain/​html_node/​Copyright-Notices.html#​Copyright-Notices|GNU project]]. 
 + 
 + 
 +==== Unit Testing ==== 
 + 
 +Testing your code is essential! 
 +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. 
 + 
 +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://​cram-system.org/​tutorials/​beginner/​testing|testing tutorial]] to get started on writing tests.