Photo by Samuel Zeller on Unsplash
I have a feeling that even when we try to use nice, descriptive names in our code, we still tend to make things too complicated. For some reason, we use this "heavy", technical vocabulary instead of plain, simple words that we would use in a conversation with non-tech people. Yes, it looks very smart and it is clear when we write it but it gets confusing over time when we have less contact with that part of the code.
I started thinking about this a lot when working on a new feature recently at work. The details are irrelevant to the idea itself, but a couple of examples might help illustrate what I mean.
At one point when using the application, the user was supposed to enter a special code in a bunch of inputs and had limited time to do so.
We needed to make sure the final "submit" button cannot be clicked until the entire code has been entered i.e. all the inputs are not empty and we had to give a name to the button-disabling condition. For whatever reason, my brain was suggesting stuff like notAllInputsFilled, invalidCodeLength, or shouldDisableSubmit. All inputs? What "invalid" means? Disable when should disable? Really? It took quite a while to settle with codeTooShort.
A while later we needed to add another condition to disable the button - the user has run out of time. Again, for whatever reason, it took us a long time to come up with "obvious" ranOutOfTime. Before we came up with it, a whirlwind of expiredCodes, expiredTokens, pastExpirationTimes, and other weird stuff came through my mind. Heh.
Struggles like this kept popping, again and again, just to implement one very simple feature. Thinking about all the codebases I've seen over the years, I think it's not just me - it's a wider problem. Of course, effective communication is always hard and code is no exception. Yet we seem so used to the technical jargon that we sometimes forget to communicate (through code) like normal human beings.
One or two names like in the "bad" examples above will not make or break a project but it stacks up. Even in a small project, we probably have hundreds of names and not all projects are small. Over time, we can't just read the code anymore, we have to "decode" it, even though we understand every single word in every single name.
So here's my little tip/wish: let's use simpler, more conversational, more human vocabulary when naming things. We'll thank ourselves sooner than we think and maybe others will too!
Top comments (3)
Very recently, I started using
small_separated_namesfor variables. For some reason I am not sure why. But still personal rules are same, variables should not be more than 3 word long, and useis_,has_,hold_etc wherever logical. Almost all other coding style rules are same as whatever language I am using at that time, except for some reason I stopped usingcamelCasedVariablesNamesat some point in past few months, favouringlower_cased_names, in all the languages, from typescript to php, to kotlin, irrespective from whatever styles that language suggest for variable names.I entirely agree with you. IMO classes, variables, and methods should reflect the business language. The names could be discovered via Event Storming sessions and implemented in Domain-Driven Design approach.
Maybe require that non-simple terms appear in a top-level file, GLOSSARY.md, to encourage reuse and consistency.