Comments clutter my overview


In this video you encourage to use a lot of comments, even for the todo lists. If i take it literally the most tekst of the PlayGame() function ends up green. This makes the code a lot less readable to me. You already pointed out that code should always be readable, so to much commenting wont help on that. What is your thought on this ?

Psuedocode itself is a practice of writing comments to lay out the main points of your design plan, since just writing in the English words of your plan will give the compiler a fit. Sometimes you’ll end up deleting those comments as you fill in the actual code (especially with TODO comments) but they can also serve as nice “signposts” in plain English what the finished code itself is doing. In larger applications, you will likely come across code that you didn’t write (or maybe you wrote it months back and now don’t remember it), and maybe it uses a library you’re not all that familiar with, and it might be not that easy to decipher what exactly a particular chunk of the code is doing. Leaving comments will help other developers (or your future self) to quickly and easily read your code and make changes or improvements to fit ever-changing requirements.
That being said, there’s a good rule of thumb to naming variables and functions that says basically that you’ve struck upon a good name if it eliminates the need for a comment. For instance,

void PrintIntro(string firstName) {
    cout << "Hi, " << firstName;

is better than

// print out the intro text with the player's name
void function1(string string1) {
    cout << "Hi, " << string1;

So you absolutely can cut down on the number of comments in your finished code by simply choosing good identifiers for your variables and functions. Hope this helps :slight_smile:

1 Like

Privacy & Terms