Style Guide

Style Guide

Readability of the code is important especially because in general the software developers of the RoboTeam changes annually. And future software developers should understand your code as well which includes software developers over the next decades. We as software developers of the RoboTeam understand that documentation/design/style/etc. are the least fun task to do, but it is even less fun for future software developers to figure out what your code does and why you made certain decision. Therefore in this file we explain which guidelines we follow.

Guidelines

• Every class should have documentation added written in Javadoc style (https://www.tutorialspoint.com/java/java_documentation.htm) with a summarized description of the meaning of the class. Moreover every class should have @author and @since tag which contains respectively the author and the date at which the class has been created.
• Every public function should also have a documentation added in the same style which contains a short description of what the function does. Has a @param tag for every used parameter which explains the usage of that parameter and what is expected from that parameter. Moreover it should have a @return tag in case the function returns something which explains what the function returns.
• Every private function which is not clear what it does (99% of the cases) should also be documented, but not as heavily as public function should be. Hence only a short description is required, tags are not required.
• Every global variable and constant for which it is not clear what it does (99% of the cases) should have a (block) comment added which explains what this variable does.
• Every part in the code for which it is not clear why it has been added should contain a comment which explains why this part of the code is necessary to have.