Making your code clean: How proper naming can save the day

naming_xkcd.png

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:

naming_1.PNG

  1. 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.

  2. 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.

  3. 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.

naming_2.PNG

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!

H2
H3
H4
3 columns
2 columns
1 column
Join the conversation now