Clean Code – Chapter 2: Meaningful Names

• Use Intention-Revealing Names

  The name should tell you why it exists, what it does, and how it is used.

  e.g.

  Bad code:

  public List<int[]> getThem(){
      List<int[]> list1 = new ArrayList<int[]>();
      for (int[] x : theList)
          if (x[0] == 4)
              list1.add(x);
      return list1;
  }

  Good code:

  public List<int[]> getFlaggedCells(){
      List<int[]> flaggedCells = new ArrayList<int[]>();
      for (int[] cell : gameBoard)
          if (cell[STATUS_VALUE] == FLAGGED)
              flaggedCells.add(cell);
      return flaggedCells;
  }

  Better code:

  public List<Cell> getFlaggedCells(){
      List<Cell> flaggedCells = new ArrayList<Cell>();
      for (Cell cell : gameBoard)
          if (cell.isFlagged())
              flaggedCells.add(cell);
      return flaggedCells;
  }

• Avoid Disinformation
• Make Meaningful Distinctions

  Bad code:

  public static void copyChars(char a1[], char a2[]) {
      for (int i = 0; i< a1.length; i++) {
          a2[i] = a1[i];
      }
  }

  Good code:

  Change the name a1, a2 to source and destination.

• Use Pronounceable Names

  这条对于我们中国人来说就不合适了，命名时还是不要用汉语拼音。

• Use Searchable Names

  The length of a name should correspond to the size of its scope.

• Avoid Encodings
  • Hungarian Notation

    特定时代的产物，随着一些现代的集成开发环境的引入，已不建议使用了。（参考维基百科词条：匈牙利命名法）

  • Member Prefix
  • Interfaces and Implementations

    leave interface unadorned.

    prefer to encoding implementations than interfaces.

    e.g. prefer to use the name ShapeFactoryImp rather than IShapeFactory.

    关于这一点，在上面提到的“匈牙利命名法”维基百科词条最后也有相关说明：

    .NET Framework，微软新的软件开发平台，除了接口类型一般不适用匈牙利命名法。在 .NET 中，习惯在接口类型前放一个 I （例如 Windows Forms 中的 IButtonControl 接口。）.NET Framework 指导方针建议程序员不要用匈牙利命名法，但是没有指明不要用系统匈牙利命名法还是匈牙利应用命名法，或者是两者都不要用。

    与此对比，Java 的标准库中连接口类型也不加前缀。

    即 Java 的命名法则与作者的观点一致。

• Avoid Mental Mapping

  Clarity is king.

• Class Names

  noun or noun phrase names

• Method Names

  verb or verb phrase names

• Don’t Be Cute

  Say what you mean. Mean what you say.

• Pick One Word per Concept
• Don’t Pun
• Use Solution Domain Names

  use computer science terms, algorithm names, pattern names, math terms and so forth.

• Use Problem Domain Names

  When there is no “programmer-eese” for what you’re doing.

  Separating solutions and problem domain concepts is part of the job of a good programmer and designer. The code has more to do with problem domain concepts should have names drawn from the problem domain.

• Add Meaningful Context

  Bad code:

  private void printGuessStatistics(char candidate, int count) {
      String number;
      String verb;
      String pluralModifier;    
      if (count == 0) {
          number = "no";
          verb = "are";
          pluralModifier = "s";
      } else if (count == 1) {
          number = "1";
          verb = "is";
          pluralModifier = "";
      } else {
          number = Integer.toString(count);
          verb = "are";
          pluralModifier = "s";
      }
      String guessMessage = String.format(
          "There %s %s %s%s.", verb, number, candidate, pluralModifier);
      print(guessMessage);
  }

  Good code:

  public class GuessStatisticsMessage {
      private String number;
      private String verb;
      private String pluralModifier;
      
      public String make(char candidate, int count) {
          createPluralDependentMessageParts(count);
          return String.format(
              "There %s %s %s%s.",
              verb, number, candidate, pluralModifier);
      }
      
      private void createPluralDependentMessageParts(int count) {
          if (count == 0) {
              thereAreNoLetters();
          } else if (count == 1) {
              thereIsOneLetter();
          } else {
              thereAreManyLetters(count);
          }
      }
      
      private void thereAreNoLetters() {
          number = "no";
          verb = "are";
          pluralModifier = "s";
      }
      
      private void thereIsOneLetter() {
          number = "1";
          verb = "is";
          pluralModifier = "";
      }
      
      private void thereAreManyLetters(int count) {
          number = Integer.toString(count);
          verb = "are";
          pluralModifier = "s";
      }
  }

• Don’t Add Gratuitous Context