Tips for commenting
- Choose meaningful and reasonable variable names (and function names) to minimize the amount of comments – use self-commenting code.
In VEXcode VR, besides following the specific Name Rules for Variables, we should select a variable name that describes what the variable contains to make the code as easy to read as possible.
The following is an example name of the variable that stores the number of blocks.
- Don’t comment on unclear code, improve the code itself instead. For example, we should avoid naming a variable with a single letter or a meaningless wordy name and then adding a comment describing its purpose. Instead, we can use a meaningful variable name and eliminate the comments.
Take the following code for example:
- Avoid over-commenting. There is no need to add comments to each line of the code. Over-commenting can obscure the readability. So don’t comment on the code where it is obvious what we are trying to accomplish. Effective comments offer supplementary information not echo the code itself.
Take the following code for example:
Well-written and well-placed comments can greatly improve our code readability, playing a crucial role in enhancing code quality, promoting team collaboration, and expediting the debugging process.
We hope this post is helpful when you’re adding comments to your project.
Please let us know if you have any questions, comments, or feedback. Thank you!
