Differences

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

--- cs:coding_conventions:start [2016/08/21 19:24]
Brandon Kallaher created
+++ cs:coding_conventions:start [2017/04/08 12:50] (current)
Brandon Kallaher
@@ Line 1: / Line 1: @@
 ====== Coding Conventions ======
+Due to this being a collaborative software project among new developers, it's important to make sure that the code you write is clean and usable by others. We predominantly use two languages in this project, C++ and Python. Below are a list of coding conventions for each respective language in the project. There may be exceptions to these rules, but otherwise they should be followed. A code linter will be created to ensure that code conforms to there standards.
-<WRAP alert>
+====== roslint ======
-This page is **stale** and needs to be reviewed. It may be deleted or radically changed in the near future.
+To check if you code passes standard checks, compile using:
-</WRAP>
+  rsmake roslint
+This will invoke the compiler with the code linter turned on. The C++ linter will run first and will fail with an error if the linter fails and the Python linter will not be run. If the C++ code passes the linter then the Python linter will be run.
+===== All Languages =====
+===Indentation===
+Spaces shall be used for indentation, no tabs. \\
+**Rational:** mixing tabs and spaces can cause major bugs in Python, and can create ugly formatted code in all other languages, so consistency is important. Although I prefer all tabs in Python, spaces makes more sense for other languages.
+===Line Length===
+The maximum length of a line shall be 80 characters \\
+**Rational:** this results in code that is readable on most screens without wrapping lines
-====== Overview ======
+===Trailing Spaces===
+Trailing whitespace at the end of a line is not allowed. \\
-  * Due to this being a collaborative software project among new developers, it's important to make sure that the code you write is clean and usable by others. We predominantly use two languages in this project, C++ and Python. Before contributing to the project make sure you understand the language you are working with completely so as to not make glaring mistakes that could be overlooked by the team.
+**Rational:** most text editors will actually automatically chop the trailing whitespace when you open a file. If people aren't paying attention, this can result in them commiting a file where they made no functional changes other than to cut the whitespace, resulting in a confusing source control history. In addition, it's just a cleanliness thing.
-  * Below are a list of coding conventions for each respective language in the project. There may be exceptions to these rules, but otherwise they should be followed.
-===== Programming Practices =====
-  * Before writing ANY code, know what you want to accomplish. Whether it's fixing a bug, adding a new feature, or cleaning stuff up, have a mental map to avoid spaghetti code and wasting your own time.
-  * Know the system you are working on BEFORE you touch it. Some portions of the software on the sub are extremely complex and require knowledge of the whole system before you can effectively contribute to it. Ask around for help if you are editing a portion of the codebase you have not touched before.
-  * Plan with others before you make major changes to something. You may be editing code that someone else had branched awhile ago. Try to isolate your development from everyone else to reduce merges and implementation conflicts.
-  * For software design refer to this wikipedia article. [[wp>Software Design]]
-===== Naming Style =====
-**File / Class Names** - Words in file / class names should start with an uppercase, be concise, and should not conflict with any other classes.
-**Target Names** - Target names should be lowercase, concise, and should not conflict with any other targets.
-**Class Members / Functions** - Class members and functions should also start with uppercase letters unless you are calling derived members of the same name in which case you can use the lowercase in order to not override the function.
-**Constants / Macros** - Constants an macros should be all caps, concise, and should not conflict with other macros.
-===== Style =====
-  * [[wp>1TBS]] should be followed as closely as possible for all C++ code. Some exceptions may occur when you have functions with lots of parameters or a call requiring multiple lines to accomplish. When it doubt, just make it look CLEAN.
-===== Optimizations =====
-  * For most contributions to the codebase, DO NOT WORRY about optimizing your code. Obviously utilize algorithms and logic that is efficient for your use case, but do not write cryptic code for the sake of speed. Also, DO NOT use 'compiler tricks' either. Compilers nowadays are very good at creating fast code. Sacrificing readability for that 0.01% increase in speed is not worth it.
-===== Commenting =====
-  * COMMENT YOUR CODE. If you are writing a class or a function give a simple, one line explanation of what it does and how it should be used. For algorithms, explain major steps that cannot be easily deduced just by looking at the code. If you write a line of code that is a bit 'hacky', that needs to be changed in the future, or has possible bugs in some circumstances, **Label It** with a comment explaining the problems.
+===Extra Newlines===
+More than one blank line in a row is not allowed. \\
+**Rational**: If you need to break up your code into logical chunks it is better to use a single newline and a comment describing the next code block.
+===== C++ =====
+running
+  astyle -A1 -N -n <file name>
+on your C++ files should clean them up nicely.
+===== Python =====
+Nodes should be defined in classes with the constructor called in the "main" section.
+<code python>
+def Node():
+    def __init__():
+        # define pubs and subs here
+    ...
+if __name__=='__main__':
+    rospy.init_node()
+    Node()
+    rospy.spin()
+</code>

User Tools

Differences

Page Tools

Palouse RoboSub Technical Documentation

Site Tools