Very early on in my career, I really got into Uncle Bob’s Clean Code video series. And from there I started scouring the web for every blog article or reading material about clean code.
Clean code just made sense. It was about organization. And from back in college, I knew of several people who were very smart. But wrote completely unreadable code. Like when they came and asked me to look over their code because they were stuck on something, I would literally just ask them a bunch of questions about their code and problem until they figured out their own fix. Because no way was I going to read that mess they called code. (And really, at the time, I sucked at reading code that wasn’t my own – it’s really an acquired skill).
And I preached about clean code to anyone that would listen (so basically my boyfriend and former tech lead). And then I somehow conned a roomful of people (twice) into listening to me rant about keeping code clean.
But I was wrong. (Sort of.)
Specifically about comments in your code base. More specifically about how comments have no place in your code base.
I’m revisiting the main reasons I supported for excluding comments in your code:
- Comments are never updated, and therefore become outdated quickly
Yes and no. For sure, code will always be up to date, and comments may or may not be updated accordingly. But the thing is, code rarely changes either. When working on a project, I’m typically adding new features. Therefore adding new code and leaving the existing code alone. Or I’m fixing a defect, so I’m changing existing code, but the intent of what the code does stays the same. Therefore the comment, which typically expresses the intent of the code stays the same.And really, if the intent is not the same – isn’t it the programmer’s responsibility to update that too? It may be english rather than C# or Java or Python, but its still part of the code base.
Why am I revising my views on this? Because when I changed jobs in January, and I had to become familiar with a new codebase. I was incredibly grateful for some of the comments I found came around. Mind you, these comments were describing high level functionality on pieces that were definitely complex. Do not litter around comments like confetti. That’s not what comments are for.
- If your methods and classes are named correctly, comments are not needed. The name of the method should tell you exactly what the code does.
Except when it doesn’t. I mean that’s why we have documentation, right? Because sometimes the name of the methods aren’t clear enough. It’s one of those things where the name of the method makes sense if you already know what the method does. But as someone who doesn’t already have that knowledge, the name gives little insight.Because the thing is, when you’re working on a large project with lots of moving parts, there is a lot of nuances in how things work and method names don’t give enough space to convey nuance. For example the simple method name “SaveThing()”. Seemingly obvious, this method saves the thing to where you store the data, the database. Duh. But what if the project saves the data in two different places? The database and an cloud based search index? But the cloud based search index was added much later. So now you have “SaveThing()” and “SaveThingToCloud()”
Or how about when you just straight out disagree with the previous programmer’s definition of a word? For example “LoadForm()” to me, would mean that after this method is called, there is a form that you can now see on the screen. Whereas the programmer before me, deemed it appropriate to mean that all the user entered data in that form is now “loaded’ into the model ready to be saved to the database.Let’s not get into the folks that think verbs “load” and “populate” should be interchangeable. Or people who, despite being native English speakers, don’t subscribe to the elements of grammar laid out in Strunk and White. Leaving us with with method names such as “AreTrue()” rather than “IsTrue()”.
Comments can be used for both good and bad. But they are not always bad. Use good judgement.