Growing up in my junior years of development, i was convinced that code comments are evil and they are the bane of our existence, i got this impression through reading various articles, books, blog-posts on why you had to do every thing but doing code comments.
But, after many trial and errors, i have came to the conclusion that code comments are sometimes necessary to the sustainability of a project. But, that doesn't negate the fact that you should always be careful with your code comments, sometimes comments can be expressed through the code itself.
Some examples of where i would comments some piece of code, the language in focus will be Ruby, and ERB templates.
I have started commenting various parts of my .erb files. One area where comments stand out are with icons. You've seen icon, and you know how they look good and that extra touch to the UI and UX. Well, that same icon would something like this in code
<svg xmlns="http://www.w3.org/2000/svg" class="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
</svg>
Can you tell me what icon is this just by looking at the code? Probably not, and most of the times you find multiple svgs on a file, what would you do to find out what svg are you editing? You might need to boot up your server and pray what you have removed is the correct one. And, here comments excel. Let's take the same code and add a comment to it.
#<% close icon %>
<svg xmlns="http://www.w3.org/2000/svg" class="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
</svg>
One line there, and some other developer, or even yourself after two months will be gratefull, because this saves you the pain of swithing to browser and seeing what is the svg you are looking for. Let's illustrate one more example.
#<% close icon %>
<svg xmlns="http://www.w3.org/2000/svg" class="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
</svg>
#<% tick(check) icon %>
<svg xmlns="http://www.w3.org/2000/svg" class="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 13l4 4L19 7" />
</svg>
#<% delete(trash) icon %>
<svg xmlns="http://www.w3.org/2000/svg" class="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16" />
</svg>
Code comments are there to help us, they are a sharp knife and we must be careful on how we use this tool and not injure ourselves while using it.
Lastly, Huge shoutout to David on his book Sustainable rails, it's really a well written book containing practical solution for your daily Ruby and Rails code.
In future blog posts i will be writing on why you should comment your Ruby and Rails code.
Thank you for taking the time to read this, have a great day!.
Related Links:
Top comments (1)
Great article Ahmad, nailed it!
I am not just a fan of those types of comments, but also documentation comments are immensely helpful too, especially when I did code in Java back in the glorious days :xD. cannot wait to read your next post (you're encouraging me to write too tbh), keep it up :)