The next practice in improving code readability is removing comments. That's right. Removing comments. I know that can come off a little controversial and we will point to all of the exceptions where you would want to keep a comment and we'll review some of those in a second. But first, let's talk about the reason for removing comments. Why do we need to remove them? What's the big deal?

for removing comments. Why do we need to remove them? What's the big deal? It's just a comment. It's not hurting anything. Rob Pike actually addressed all of this almost 40 years ago in one of his essays on programming, and I wanna break down one of his quotes. He said, I tend to err on the side of eliminating comments for several reasons. First, if the code is clear and uses good type names.

of eliminating comments for several reasons. First, if the code is clear and uses good type names and variable names, it should explain itself. Now, many get too focused on the good type names and variable names. What he is really saying here is if the code's clear, it should explain itself. Now, I don't think he's referring to the dream of self documenting code. What he's talking about here is the same thing

of self documenting code. What he's talking about here is the same thing we've been talking about. Code that's clear, meaning it explains itself. It's easy to understand at a human level. That's exactly the code we're trying to write, and if we have code like that, we don't need comments. Second comments aren't checked by the compiler, so there's no guarantee they're right, especially after the code is modified.

so there's no guarantee they're right, especially after the code is modified. A misleading comment can be very confusing. How often have we come across code that does one thing, but the comment says it does another? Which one's right? Well, of course the code is comments aren't even run. Most languages completely strip the comments when parsing code. So that comment can say something all at once.

when parsing code. So that comment can say something all at once. It doesn't matter. The code is what runs, in which case we should focus on improving the code, not necessarily the comment. And his third point is an issue of typography. Comments, clutter code. Again, this goes back to his second point and something we talked about in dead code. Comments aren't run, so they don't matter, they're dead.

and something we talked about in dead code. Comments aren't run, so they don't matter, they're dead. But as humans, we still end up reading them. If they don't have any value, then they're just cluttering the code. It's just more we have to read. That's cost without benefit, so we should remove them, therefore removing the noise and increasing the signal of the code. Now let me address some of those exceptions.

and increasing the signal of the code. Now let me address some of those exceptions. Doc blocks are not comments, although technically they use a multi-line comment syntax, their purpose is to document blocks of code, either by adding additional descriptions or type information. Another exception is meta programming. For example, PHPUnit historically used annotation within doc blocks to denote test cases or data providers.

historically used annotation within doc blocks to denote test cases or data providers. Another exception are comments which explain, I'd argue this is a form of documentation. Either way, these comments shouldn't be removed and the difference is that they explain at a human level why the code exists. So to be more specific, what we're really talking about removing here are inline comments, not only in syntax

what we're really talking about removing here are inline comments, not only in syntax but their proximity to the code. Furthermore, into Rob Pike's points, comments that don't add additional value beyond what the code is already explaining or what could be explained through code said another way, comments that are simply telling us what the code is doing, not why the code is doing it that way. Let's go through a code sample

not why the code is doing it that way. Let's go through a code sample and challenge ourself to remove its comments. This is a Twitter client that has a method called recentTweets. And from the comments, we can see that it gets the tweets since yesterday. For the handle on the surface, that comment is giving us a bit of human context, but this is before we've jumped into the code.

that comment is giving us a bit of human context, but this is before we've jumped into the code. So before we remove this high level comment, let's review the body of the method to see if the code's clear enough that it can be removed. The very first line of code also has its own comment. It tells us the following code is the date for yesterday. Now, I think most php developers could determine that this code holds the date for yesterday, but can the code be more clear?

that this code holds the date for yesterday, but can the code be more clear? That is clear enough to remove this comment, and I think it could be, although pretty redundant. This comment does have some value. It explains the value that this variable holds, but we could make that more clear by simply changing the variable name to RobPikesPoint. If the code has good naming, it should be clear enough to explain itself.

If the code has good naming, it should be clear enough to explain itself. So let's change the variable name to yesterday. In doing so, this comment really is only telling us what the code is doing. Furthermore, many developers could read the variable name alone, but if not just the function that's being called to quickly understand what this line of code does potentially faster than they could read the comment itself. Either way, I think we're safe to remove it.

potentially faster than they could read the comment itself. Either way, I think we're safe to remove it. Let's go down to the next comment. Again, it's explaining what the next line of code does. It's telling us that this is an array of recent tweets to return. Again, we can quickly see the value of this $variable. So I think array is unnecessary. We'll go ahead and strip that down from the comment. Now, while $rentValue is an abbreviation,

We'll go ahead and strip that down from the comment. Now, while rentValue is an abbreviation, and we should expand that to return value, it is historically conventional enough to maybe understand this is a value we're going to return. That allows us to remove this piece of the comment. Now we're simply saying the next variable is for recentTweets. Just as before, we could give this a much better variable name.

Just as before, we could give this a much better variable name. So we'll call it just that recentTweets. In doing so, we can safely remove this comment as it adds no additional value at this point, it's just cluttering the code. Moving on to the next comment. This one's a bit longer and it does seem to be relaying something more than this code does on the surface.

and it does seem to be relaying something more than this code does on the surface. So I'm gonna skip over it for now to see if we have any more quick wins. Here's another comment that's seemingly long, but if we look at the contents, it's really just telling us what this code is doing. Now it's summarizing it for us nicely, but again, if we were able to tighten up this method, the context of the surrounding code

but again, if we were able to tighten up this method, the context of the surrounding code may explain that for us. And again, this code isn't necessarily that complex. While this condition feels a bit long, the syntax of the code is simply a loop with a single if statement. And now that we've renamed this variable, I think most developers could scan this and see on their own without the comments that this is some kind of accumulation.

and see on their own without the comments that this is some kind of accumulation or we're building up this array. At that point, they could decipher this seemingly long conditional, so I would feel safe to remove this. That brings us to the final comment, and again, it's simply stating what the code below does. Return recent tweets. So with our refactor, this comment too is unnecessary.

Return recent tweets. So with our refactor, this comment too is unnecessary. So we've reached the bottom of the method and at this point, I think again, with a bit of naming, we could remove this comment. The value that this comment provides that the code doesn't is since yesterday specifically tweets since yesterday. It's expanding in a more human way. What recent means? So I would argue the method name should actually be this.

It's expanding in a more human way. What recent means? So I would argue the method name should actually be this. That is tweets since yesterday. And in doing so now the code reads exactly like the comment, so we can remove it. Now, just as Rob Pike predicted with some simple naming and typing, we were able to get rid of almost every comment. The only one that remains points back to some of the exceptions that we covered. In this case, this code is explaining why we are using the

of the exceptions that we covered. In this case, this code is explaining why we are using the User timeline because it gives us more control over response data. This comment prevents a future programmer from coming in and changing this to maybe some kind of different endpoint on the surface. This might seem like the correct endpoint to use to get tweets since yesterday, but the comment lets us know that we need

to get tweets since yesterday, but the comment lets us know that we need that control over the response data and therefore shouldn't make the change. Since we're leaving this comment, I would spend a minute to just make it a bit more human readable. Maybe something like we use the userTimeline endpoint point because it gives us more control over the response data period.

because it gives us more control over the response data period. It's not exactly the perfectly cascading three line comment you'll see in the Laravel framework, but since we're choosing to leave this comment, let's make it a little more readable for the next human. So that's the practice of removing comments. I know this practice can be a bit debated, so I've tried to demonstrate some of the exceptions, but even with those, I have to say on a personal note,

to demonstrate some of the exceptions, but even with those, I have to say on a personal note, being challenged to remove comments was the single best piece of programming advice I've received. It forced me to start thinking about the code and how it might feel to other humans that put me on the path to readability. So now I'm passing that advice onto you. Try it out, see how it goes.

Try it out, see how it goes.