I will be honest, I suck at naming things, be it a variable, a class or a method. I just can't come up with a good name! You might think it's a trivial thing, but let me assure you, it is very important to have good, descriptive and consistent names. They make your code clean.
In my office, we have 'Lunch and Learn' events where the whole team comes together and watches better coders talk about coding. We are watching Uncle Bob's Clean Coder video series. Uncle Bob is quirky, fun, and above all, a veteran programmer. He co-authored the Agile Manifesto which many companies follow religiously. Today's episode was about naming stuffs and I found it really helpful. The best takeaway from the episode was this: if you need to look at comments or see the code to know what the variable/method is doing, you named it badly. This is the crux of the lesson. Grady Booch, author of Object-Oriented Analysis and Design with Applications said "Clean code reads like a well written prose". That will be our aim whenever we are naming things. While naming, keep these following in mind:
Reveal your intent through the name: Be descriptive. Don't shy away from saying what your variable/method does, so that you don't need to add a comment saying what it does. And please, for the love of God and everything that is holy, don't name things like: int i, string x, bool aa. I don't want to go to the documentation to figure out what it means. It might be easier for you to use a short name but later down the years when a poor engineer is reading through your code, I can guarantee he/she will appreciate it a lot if your code reads well. Debugging is hard enough by itself. Don't let your laziness make it harder.
Avoid disformation: Don't use obscure self made prefixes or suffixes. You might think naming a variable c_BookID is a good idea since you know BookID is a constant but I don't know that. No one should know that! Someone might interpret it differently and that's on you.
A point Uncle Bob made really stuck out to me because I never thought of it before. Make sure your names are pronouncible since a lot of people will be talking about it. Don't name something mq_pwdb (a name he actually saw once). How am I supposed to pronounce it when I'm talking about it with someone else? It might sound trivial but it does make our lives easier as a programmer when everything flows smoothly from our tongues.
Name things so that they read like nicely written English sentences. I really liked this points. Variables and classes are nouns. Methods are verbs. Boolean variables are predicates. Abstract classes should be generic and derived classes should be descriptive. If we use the parts of speech properly while naming, the code reads like sentences and it is so much easier to understand.
See how naming things properly make the code look crisp and clean? If you use the proper parts of speech while naming, the code will read like prose, and thats a sweet sweet feeling. Also, a disclaimer: I cut some corners while writing up the example above. There's nothing called "datetime.Friday". But that's not the point of the article.
I hope you will try to keep these in mind while you write your code. I surely do and I have started to see the benefits. My code reads well and code reviews go faster. Clean code ftw!
Basically the more your code reads like prose, the less need there is, for you to have to describe what you are doing in the comments. Instead of describing the "what" of your code you can then describe the "why".
You can describe the reasons you have chosen to do something, instead of what it is you're doing.
Good post!
Thank you!
Great share! I wish more people wrote code like this.
Uncle Bob is actually Robert Martin and he wrote a book called Clean Code that is an extensive treatise on these principles, well worth your time.
Another aspect of naming that I follow consistently is to name all of my objects as identifiable nouns. Don't just say
userbut more specifically likecreatororeditor. These nouns should be understandable not only to the developers, but be identifiable by the end users as well.Then, all methods we write are verbs, still identifiable and following these same principles.
I love Clean Code! Tons of great stuff to learn! He is an....interesting person, to say the least. And I do like the identifiable nouns idea. Surely makes the code more readable. I am going to keep this in mind when I make my next 'user' variable.
You know you have to change your habits when you name your variable aa because of the 26 a-z ones before.
Lmao! Or A1...A11