Quata 1: Naming

feature image

Quata 1: Naming

Here it is, guys. The first ever quata.

I’ll start with proper naming of classes, methods, and variables. It’s one of the most important code quality skills you’ll want to master. You want your code to be expressive. You want it to be readable by other developers, and by the future you. Readability is maintainability, and proper naming plays a big role in that.

Java keywords and the JDK ‘terms’ are (mostly) in English. So, it certainly helps and is absolutely possible to have your code read like English. You just need to choose your names wisely.

The following is a very simplistic (i.e. not production-ready, as I anticipate most of my examples will be) implementation of a bank checking account. What would you change?

import java.util.ArrayList;
import java.util.List;
import java.math.BigDecimal;

public class ChkAcct {
  private BigDecimal availBal;
  
  public ChkAcct(BigDecimal amt) {
    availBal = amt;
  }
  
  public BigDecimal get_avail_bal() {
  	return availBal;
  }
  
  public void add(BigDecimal amt) {
	availBal.add(amt);    
  }
  
  public void subtract(BigDecimal bdAmount) {
    if (checkAmount(amt)) {
      availBal.subtract(amt);
    } else {
      throw new IllegalArgumentException();
    }
  }
  
  public boolean checkAmount(BigDecimal amt) {
    return availBal.compareTo(amt) >= 0;
  }
  
  public boolean isNotPositive() {
    return availBal.signum() <= 0;
  }
}

Here’s what I would correct:

Line #CommentSuggested Correction
MultipleIt’s littered with unnecessary abbreviations. Some developers try to save time typing by shortening their variable names. Today’s IDEs have superb auto-complete features that you almost never need to type the whole thing. These abbreviated names are harder to read. Spelling them out makes the code read more naturally.Spell them all out.
8, 16, 20Names should match the abstraction.

The constructor parameter amt is too generic. While you can kind of tell what it means, it needs to be more explicit than that.

The method names add() and subtract() are too technical and low-level.
Rename the constructor parameter to startingBalance.

Rename the add() and subtract() methods to the more context-appropriate deposit() and withdraw(), respectively.
12, 20Java uses camelCase for its naming convention. We should stick to it for consistency.

People coming from other languages tend to carry over their previous language’s naming convention.

The Hungarian notation, where you encode the type information as a prefix (the bd on line 20 stands for BigDecimal), is meant to assist developers writing in loosely-typed languages, which Java is not. It doesn’t serve any purpose in Java. It just causes disruption, therefore slowing you down.

I don’t know if there’s a term for the convention with underscores (please leave a comment if you know what it’s called), but while it’s not harder to read (probably easier for some), it’s just very un_java. Oops, I meant unJava. Consistency is king. Unless your entire organization has adopted that convention, stay away from it.

By the way, as you may know, underscores do have their place in Java constants. The convention is all-uppercase with underscores separating words, e.g. DEFAULT_STARTING_CHECK_NUMBER.
getAvailableBalance()
amount (drop the bd prefix)
21, 28checkAmount(), besides being vague, is not worded properly. It returns a boolean value. Its name should therefore be in a form that yields a yes-or-no answer.mayWithdraw()
32Negatively-named variables and method names usually make for very confusing expressions. Imagine calling !isNotPositive(). Ouch! That double negative hurts my brain.hasBalance(). I realize it changes the method altogether, but your callers will use what is made available to them.

Here’s the version with my corrections:

import java.util.ArrayList;
import java.util.List;
import java.math.BigDecimal;

public class CheckingAccount {
  private BigDecimal availableBalance;

  public CheckingAccount(BigDecimal startingBalance) {
    availableBalance = startingBalance;
  }
  
  public BigDecimal getAvailBalance() {
  	return availableBalance;
  }
  
  public void deposit(BigDecimal amount) {
	availableBalance.add(amount);    
  }
  
  public void withdraw(BigDecimal amount) {
    if (mayWithdraw(amount)) {
      availableBalance.subtract(amount);
    } else {
      throw new IllegalArgumentException();
    }
  }
  
  public boolean mayWithdraw(BigDecimal amount) {
    return availableBalance.compareTo(amount) >= 0;
  }
  
  public boolean hasBalance() {
    return availableBalance.signum() > 0;
  }
}

How did you do? Do you disagree with some of my recommendations?

There are other naming issues that I did not cover here. You can expect more quatas on proper naming in the future.

Leave a Reply

Your email address will not be published. Required fields are marked *

Post navigation

  Next Post :