Avoid Abbreviations
| | class Logbook { |
| » | static final Path DIR = Paths.get("/var/log"); |
| | static final Path CSV = DIR.resolve("stats.csv"); |
| | static final String GLOB = "*.log"; |
| | |
| » | void createStats() throws IOException { |
| | try (DirectoryStream<Path> dirStr = |
| | Files.newDirectoryStream(DIR, GLOB); |
| | BufferedWriter bufW = Files.newBufferedWriter(CSV)) { |
| | for (Path lFile : dirStr) { |
| | String csvLn = String.format("%s,%d,%s", |
| | lFile, |
| | Files.size(lFile), |
| | Files.getLastModifiedTime(lFile)); |
| | bufW.write(csvLn); |
| | bufW.newLine(); |
| | } |
| | } |
| | } |
| | } |
Abbreviations are one step up from single-letter names, and our world is full of them: ASAP, FYI, TGIF, AFK, NASA, FBI, CYA, NYPD, and so on. Many programmers like to create their own abbreviations in their code. The obvious problem is that they’re the only ones who know those abbreviations—everyone else has to learn them first. And learning takes time. That’s why it’s better to avoid abbreviations altogether so that others can grasp the code more quickly (and have fewer WTF moments[32]).
You can read a lot of abbreviations in the code above: DIR, CSV, GLOB, dirStr, bufW, lFile, and csvLn. Do you know immediately what they refer to? For some you might, but probably not for all.
Out of context, it’s hard to determine what bufW or dirStr means. Together with the variable types BufferedWriter and DirectoryStream it becomes more obvious, but it’s still unnecessarily hard.
And what the heck does GLOB stand for? It’s actually a way to refer to sets of file paths common in Unix environments, which is what the code above is for—for example, all Java files via *.java. But you have to know that first.
Sometimes people abbreviate only parts of a variable: lFile or csvLn. We have to channel our inner Sherlock Holmes to figure out what the l or Ln mean.
So what should we do with abbreviations?
| | class Logbook { |
| » | static final Path LOG_FOLDER = Paths.get("/var/log"); |
| | static final Path STATISTICS_CSV = LOG_FOLDER.resolve("stats.csv"); |
| | static final String FILE_FILTER = "*.log"; |
| | |
| » | void createStatistics() throws IOException { |
| | try (DirectoryStream<Path> logs = |
| | Files.newDirectoryStream(LOG_FOLDER, FILE_FILTER); |
| | BufferedWriter writer = |
| | Files.newBufferedWriter(STATISTICS_CSV)) { |
| | for (Path log : logs) { |
| | String csvLine = String.format("%s,%d,%s", |
| | log, |
| | Files.size(log), |
| | Files.getLastModifiedTime(log)); |
| | writer.write(csvLine); |
| | writer.newLine(); |
| | } |
| | } |
| | } |
| | } |
The rule is quite obvious: only use abbreviations that are very common, and use long names for the rest.
Just look at the code above. It’s much easier to comprehend, and we don’t stumble upon strange variable names anymore.
First, we renamed the three fields from DIR, CSV, and GLOB to LOG_FOLDER, STATISTICS_CSV, and FILE_FILTER. In our view, CSV (comma-separated values) is the only abbreviation in the code that’s sufficiently well-known. We kept it and added a little bit more context to it. Next, we replaced the abbreviations DIR and GLOB with concise unabbreviated names. FILE_FILTER conveys the variable’s intent much better than GLOB.
You don’t always have to spell out abbreviations in full. For bufW, the full name would be bufferedWriter. We just use the second word writer because that’s its purpose here. The fact that it has a buffer is less important. And as the replacement for dirStr, the short name logs seems much more informative than the full name directoryStream.
Lastly, we renamed the variable csvLn to csvLine. Its purpose is to indicate that it contains a line (of a CSV file), so why shouldn’t we just call it line, too?
To sum up, you should try to avoid abbreviations and use them only if they’re very common. If in doubt, spell it out!