-2

I have been reading the source code of some Java library classes, specifically CompletableFuture. I noticed that the authors are making extensive use of cryptic (single-letter) variables in the code, which makes the code arguably unreadable and difficult to track.

Is there a specific reason/rationale behind this approach ? (since the official Java naming conventions suggest semantically-rich variables naming, avoiding single letter variables, except in specific contexts, such as for loops)

I found this related question, but I think it's not a duplicate, since I am talking about the standard libraries of Java (not snippets or tutorials), which should ideally be optimal in terms of maintainability and readability.

I also think that answers to these questions are not highly opinion-based, because they have to be backed up with data in order to be solid. For instance, @Jorg's answer below is backed up by a very thorough explanation, showing how single-letter variables might be part of the domain model and instead be intent-revealing to experienced engineers (especially for non-public, internal components).

Community
  • 1
Dimos
  • 419
  • 2
  • 10
  • 1
    Possible duplicate of [Is the use of one-letter variables encouraged?](http://softwareengineering.stackexchange.com/questions/285288/is-the-use-of-one-letter-variables-encouraged) – gnat Feb 03 '17 at 16:53
  • Are you reading the actual source, or reading the output from a disassembler? – whatsisname Feb 03 '17 at 17:23
  • @whatsisname The [real code (careful – huge website)](http://grepcode.com/file/repository.grepcode.com/java/root/jdk/openjdk/8u40-b25/java/util/concurrent/CompletableFuture.java#CompletableFuture) uses single letter names for local variables. I find it mostly OK (“small names for small scopes”), especially since the code is superbly documented. But I'd absolutely flag some parts during a code review. – amon Feb 03 '17 at 17:27
  • @whatsisname, I've used grepcode which has the exact source code and to be more specific I am referring to the ``doThenApply`` method – Dimos Feb 03 '17 at 17:31
  • @gnat, I stumbled on this, but I do not think that it's a duplicate because I'm talking specifically about the standard libraries of Java (not tutorials or snippets), which should ideally be as maintainable as possible. – Dimos Feb 03 '17 at 17:33
  • 2
    I agree, this is not a duplicate of that question. However, it is not answerable by anyone on this site unless said answerer happens to be a former Sun employee who wrote the code to begin with. –  Feb 03 '17 at 17:36
  • @Snowman, I see your point. I also acknowledge that it's a quite open-ended question, but for new aspiring software engineers such findings create several misunderstandings. That's the reason I opened that question. And btw, this code is from Java 8 released recently (not any obsolete code), so there is probably someone that could shed some light. – Dimos Feb 03 '17 at 17:41
  • 1
    @Dimos we get this question on a regular basis - not every day, but often enough - "why does this code in some standard library published by vendor or open-source group X violate some quality standard I was taught?" The answer is always the same: 1. ask the people who wrote it, because your guess is as good as mine and 2.a. my guess is because we all have deadlines to meet and sometimes we rush and quality is not as good as it could be or 2.b. just because someone is writing standard library code does not mean they are a good programmer. –  Feb 03 '17 at 17:45

1 Answers1

5

Identifiers should describe the semantics of the things they are identifying in the domain language such that they can be easily grasped by domain experts. I am not an expert in the domain of low-level concurrent standard library API implementation on the HotSpot JVM, so I cannot say authoritatively whether or not those variable names make sense.

There are a few I can comment on, however:

  • fn is a widely-used abbreviation of "function".

  • It is common in functional programming to simply call an entity of an unknown type x and a collection of such entities xs (i.e. "exes" with a plural-"s" to indicate a collection). If it is a value that has the type of a type variable, then it will often be named after that type variable, i.e. the two arguments of a function of type (A, B) → C will often be called a and b. You can see that in some instances here:

    • t is an unknown value of the unknown type T,
    • u is an unknown value of the unknown type U,
    • tr is r casted to T.

  • ex is a standard name for an Exception object in Java.

  • e is an Executor.
  • r is the result.
  • I believe p is a promise.

In general, coming up with names in highly abstract, general code can be challenging, because, well, it's highly abstract and general: it is supposed to work in many different contexts with many different things of many different types, completely independent of any particular domain.

Jörg W Mittag
  • 101,921
  • 24
  • 218
  • 318
  • Thanks for your answer, very insightful! So, it seems few-letter variables might sometimes improve readability indeed, due to being close in a specific domain model (thus easily understandable by experts) and also due to referring to abstract notions. – Dimos Feb 03 '17 at 18:54