Code Documentation

Table of Contents

1. Overview
2. Coding Tips
   a. Plan your Code
   b. Test as you Write
   c. Follow a Format
   d. Comment your Code
   e. Readmes
   
3. Links
   

Overview

There are two types of code; spaghetti code and structured code. Spaghetti code is usually written without prior planning, tends to sprawl over hundreds of lines, and isn't generally understandable by any other researcher once it has been written. This kind of code is frequently generated by students working in isolation on a task, and doesn't often withstand the test of time. In contrast, structured code has been thought out and structured, with frequent explanatory comments, such that it can be used both in application and as an example for future work. The following are tips on writing structured, documented code.

Coding Tips

1. Plan Your Code
   Before sitting down to keyboard mash your program like a monkey with a typewriter, take a work session and structure your code writing. This structuring can take many forms, but one easy way to do this is to write pseudo-code using comments in the file where you intend to place your final code. With each line, write in plain English what needs to happen. This structure can be as general or as specific as you would like to be; the intent is that once you have everything your program needs to do in plaintext, you need only to return to the beginning of the program and translate each line into syntactical code.

2. Test as you Write
   A common hubris seen in beginner programmers is the tendency to write large chunks of untested code before testing anything. This method feels good when it works, but frequently devolves into a long list of complicated, cross-coupled errors and bugs that can take large amounts of time to fix. To avoid this, start by implementing a basic functionality in your code. Then, every time you make a significant change, test the code before moving on. The more frequently you test, the more quickly you catch errors and the more obvious it is where the error was introduced.

3. Follow a Format
   Before you were born, people who were already stellar at programming created coding styles that are conducive to understanding. Even if you think you know better, swallow your pride and look up some general styles. These tips help you name variables, constants, functions, etc. They tell you what and where to comment and how to manage curly braces.

• C++ Style convention: Link 1
• C++ .h vs .cpp file documentation: Link 2

4. Comment Your Code
   Many programmers believe that good code speaks for itself. However, code that speaks for itself is rarely helpful to the beginner or novice programmer looking to expand their toolbox. In order to make your code maintainable in the Robolab, you need to comment liberally. There should be a comment at least every few lines of code, and multi-line comments for separate functions or chunks of code that perform a specific task. These comments allow your code to be used not only in it's intended purpose, but also as an example for the students who come after you. [TODO Insert example links of code commenting protocols here]

5. Readmes
   Even with good comments in code, sometimes it's overwhelming to look into a folder and see twenty files from various different projects. Readmes are here to rectify that. Once you've created your script or file, open up the README.md file in that folder (or create one if it isn't there) and enter a new heading about your script. This file is a good way to get a quick overview of the purpose and contents of a folder. Example:

### temp_file.py
Takes no arguments, prints the string "Hello, World!" 
to the console in which it was run, and doesn't quit 
using Ctrl-C.

Links

1. C++ General writing conventions (link)
2. C++ Function Documentation Header vs. Source (link)
3. C++ Header and Source Handling (link)
4. Semantic Versioning (link)