When coding in VEXcode VR, our goal is not only to ensure that the code can instruct the robot to complete tasks but also to make sure that others can read and understand our code easily- this will help people know what the code does quickly, reducing debugging time and fostering collaboration.
How to enhance the code readability? Using effective comments plays a crucial role!
Create comments in VEXcode VR
In VEXcode VR Blocks projects, there are two ways to create comments:
- Add a note
Right-click or long-press anywhere in the Workspace, select ‘Add Note’ (Image 1) and then type the comments into the note (Image 2).
For more information about using notes in a VEXcode project, please see this article.
- Use a comment block
Add a comment block(Image 3) in the project and then type in the text of the comments.
In VEXcode VR Python projects, all comments start with a # (pound) symbol. We need to type the comments after the # (Image 4).
For more information about Comments in VEXcode VR with Python, please see this article.
Add effective comments to the projects in VEXcode VR
- Place comments that let people know what the code does and the settings for the robot.
When we start programming, we should place comments in a note (Blocks projects) or at the top of the project (Python project), providing the project description and the settings for the robot. By simply reading the comments, others can understand the purpose of the code even without having to look through the code and select the corresponding settings for the robot to run the project successfully.
Let’s take a look at the following example. The project intends to drive the robot to pick up a Green Triball and score it into the Red Alliance Goal on the Over Under Playground.
However, if we share the code with our team members without providing any extra information about the Pre-Match settings, our team might just use the default Pre-Match settings to test the project, which will cause task failure.
Therefore, we should use comments to provide the necessary Pre-Match setting information in our project. These comments will help our team members use the Pre-Match checklist to select the appropriate setting for the robot and ensure the robot completes the task properly.
- Place comments that help others understand the code and the algorithms used in the project.
1）Add comments above the code where it is not obvious what we are trying to accomplish. These human-readable comments can help others understand the purpose of using the code and learn to use it within their own program.
For example, we can place a comment that explains the purpose of using the spin ArmMortor to position block.to help people learn how to use this block to raise the Robot’s Arm to complete the task on the Slapshot Playground.
2）Place comments for the major loops or control structures, describing the strategies behind the code and what is to be accomplished.
These comments can not only help others understand the algorithms used to accomplish the purpose but also make it easier to modify the code according to future requirements.
In the following example, we add the comment above the loop to state its purpose – repeat the drive and turn actions five times to draw a star on the Art Canvas+ Playground.
- Add comments that can help to make finding the bugs faster.
When developing a significant project in VEXcode VR, the program tends to become lengthy, and the logic can grow intricate. When bugs arise, well-placed comments can navigate us through the code and help us pinpoint potential issues quickly and precisely.
Based on the detailed situations, we can add corresponding comments that may help us locate issues in the future. Here are two examples.
1). Use comments to mark key information. So that when a bug related to the key information emerges, the comment will help us easily find the code that needs to be modified.
For example, in the project that solves the following Tunel Maze on the Wall Maze + Playground, we can add a comment indicating the condition for the robot to turn. If the robot hits the wall after turning, we only need to modify the parameter value in the commented code.
2). Use comments to create section headers that describe the purpose of a particular block of code or a group of related functions. Therefore, when a bug arises, the comments can help us scan the lengthy code easily and find relevant parts.
In the following example, when we run the project on the Over Under Playground, the robot cannot score the Field Preload Triball. By reading the comments, we can quickly find the relevant part of the code for debugging.
To be continued.
Hope this information helped and please let us know if you have any questions, comments, or feedback. Thank you!
