Students often ask, “Why is it important to put comments in your code?”. Great question! This section will offer some reasons why it is so crucial to add in comments and also provide advice on the best way to do it.
As a full-time software developer all I can say is … please comment your code for the sake of future you! So often, I’ll dive into Vidcode’s codebase to tweak a feature or squash a bug, only to scratch my head at some code I wrote a few months ago, but can’t decipher now.
Have you ever had an amazing idea as you were falling asleep, and you scribbled it on some paper on your bedside table, but when you wake up you see that you’ve written “mushrooms but orange” and you have no idea what you meant? Writing code but not commenting it is a lot like that.
So, what’s the best way to do it?
- Explain your constants! If you have a variable that’s set to 36, or “Music”, or some other static piece of data (this is called ‘hardcoding’ in CS lingo), put a comment above it to remind yourself why you chose that value!
- Summarize your functions and objects! Include a comment above your functions and objects to explain what it does, what arguments it takes (if any), and what those arguments are.
- Clarify dependencies! Does part of your code rely on the proper functioning of another part of your code to work? Write that in a comment!
Comments don’t have to be long (in fact, they should be as short and concise as possible) but they are super helpful if used correctly.
Definitely! This will help others when they remix your code as well.