• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Ron McLeod
  • Paul Clapham
  • Bear Bibeault
  • Junilu Lacar
Sheriffs:
  • Jeanne Boyarsky
  • Tim Cooke
  • Henry Wong
Saloon Keepers:
  • Tim Moores
  • Stephan van Hulst
  • Tim Holloway
  • salvin francis
  • Frits Walraven
Bartenders:
  • Scott Selikoff
  • Piet Souris
  • Carey Brown

Five Lines of Code: Readability

 
Greenhorn
Posts: 14
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Good day,

Should readability always be preferred over brevity of code, especially if working in a team?

Thanks.

 
Marshal
Posts: 70234
282
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Why are you suggesting there is any conflict between readability and brevity? Unless you have the sort of code that comes up in Obfuscated C contests.
 
Author
Posts: 31
8
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Jose,

Thank you for your question.

I think you are asking whether to prefer universal readability (ie. can be read by anyone) or concision (as small as possible). This is what I imagine:


vs.


Usually, this is only relevant when onboarding new team members, because everybody on the team usually gets used to whichever style pretty quickly. So the trade off is: the second one is more verbose, but new members would easier read it. Knowing that, I would say if your team tends to have a lot of members coming on and off go for a more verbose style. If you have a more static team then make and follow whatever idioms you agree on.

My rule of thumb is: the more often something is used the shorter the name should be. Like the most used words in English are also the shortest.

 
Campbell Ritchie
Marshal
Posts: 70234
282
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Christian Clausen wrote:. . .  the most used words in English . . .

I believe the most used word in [spoken] English is “I”, and I am used to using i as a loop index.
 
Marshal
Posts: 15877
265
Mac Android IntelliJ IDE Eclipse IDE Spring Debian Java Ubuntu Linux
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Maybe i vs. indexToLoopOverArray is not the best example though. In that specific case, I doubt a newcomer (presumptuously speaking for newcomers here) would find the latter easier to read than the former. If it's just an index into an array, I'd bet that i is understandable enough.

Names are more important in uncommon or less idiomatic contexts though. I prefer names that reveal intent vs. names that are about implementation. In a recent discussion, OP was using names like mapOfNumbers which didn't really mean much in the context of the problem. I don't know if we ever agreed on a good name for that particular object though. Finding a good name can be a challenge sometimes.
 
Ranch Hand
Posts: 97
1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Christian Clausen, maybe a better example would be the snippet I posted in the thread Algorithm to eliminate code duplication where there is a code duplication in order to process remaining data, however that duplication could be avoided by adding one more counter and check in one single block of code.
 
Christian Clausen
Author
Posts: 31
8
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
The example was mostly meant to illustrate the difference between brief variable names and descriptive ones. Whether they were good names or not was not important for my reasoning. Naming is notoriously one of the hardest things in computer science. Names are also highly dependent on context, which I did not want to dwell on

However, if the question of brevity is not minded on naming but on duplication -- as Jorge suggests -- it is another question entirely. Usually, code duplication is a hint at some unexploited structure in the code, in which case it goes away through refactoring. Rarely does this make the code smaller.

 
Ranch Foreman
Posts: 113
6
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Junilu Lacar wrote:Maybe i vs. indexToLoopOverArray is not the best example though. In that specific case, I doubt a newcomer (presumptuously speaking for newcomers here) would find the latter easier to read than the former. If it's just an index into an array, I'd bet that i is understandable enough


I can remember when I first started reading code seeing code that had one letter variables. Like for example a for loop, I kept wondering why do we use i, and not naming what i is?  I couldn't understand it and would read it over and over. I would have preferred the indexToLoopOverArray much more than i. But...........now, after 4 months of coding something every day I get it and could take either or. I still have a little of an issue if I go to a websites that just love to provide examples with one letter variables but I am getting better at understanding the code.

One other example, is when creating a Scanner object, so many people type Scanner scanner = new Scanner(System.in); I kept wondering why do we use the lower case variable scanner? So I started using myScanner because I was confused with Scanner and scanner, and using myScanner I was able to keep the variable separate from the class in my mind. Now, 4 months later I am using scanner...go figure. The way I look at it whatever works.
 
Junilu Lacar
Marshal
Posts: 15877
265
Mac Android IntelliJ IDE Eclipse IDE Spring Debian Java Ubuntu Linux
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
The key really is what Christian said: "brief vs descriptive." When you were first starting out, it hadn't sunk into your brain that the variable i in a for loop represents the index into whatever it is you're iterating over. After a while, you get it. That's when your brain has made the association between "i" and "index" and the use of the shorter version becomes more idiomatic to you, i.e., it has a special meaning. Before, it didn't and therefore, a more descriptive name would have helped you.

This is why it's good practice to learn the idioms of whatever language you're using. When I was learning Go, my brain rebelled against the use of short variables. After a while, however, I started recognizing the patterns and idioms and soon enough found myself using short and otherwise non-descriptive names as well. Not that I particularly liked it but sometimes conforming to a norm is better than just doing your own thing, especially when you're working in a codebase where multiple experienced people work as well. Those people are going to expect code to be written in certain ways and going against the grain can often hinder rather than help readability. That's not to say I never go against the grain if I have a strong objection but always consider idioms and existing norms when working in a team environment.

Thanks again for sharing your take; it really is useful.
 
bryant rob
Ranch Foreman
Posts: 113
6
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Junilu Lacar wrote:The key really is what Christian said: "brief vs descriptive." When you were first starting out, it hadn't sunk into your brain that the variable i in a for loop represents the index into whatever it is you're iterating over. After a while, you get it. That's when your brain has made the association between "i" and "index" and the use of the shorter version becomes more idiomatic to you, i.e., it has a special meaning. Before, it didn't and therefore, a more descriptive name would have helped you.


You stated it perfectly. What is kind of funny is any time I see a lower case i I think index.

 
Put the moon back where you found it! We need it for tides and poetry and stuff. Like this tiny ad:
Thread Boost feature
https://coderanch.com/t/674455/Thread-Boost-feature
    Bookmark Topic Watch Topic
  • New Topic