Naming - alexdaube/My-Software-Engineering-Guide GitHub Wiki

Naming

Why?

  • Improve the maintainability and comprehensibility
  • Avoid utilisation errors
  • Avoir bad interpretation
  • Replace comments
  • It's an investment

Rename when?

  • All the time...
  • Change of behaviour
  • If there is an error
  • Ambiguous terms
  • Someone does not understand

Rules

    1. Name that reveal what is intended => Why it exists?; what is the goal?; how it is used?
public List<Cell> getFlaggedCells() {
    List<Cell> flaggedCells = new ArrayList<Cell>();
        for (Cell cell : gameBoard)
            if (cell.isFlagged())
                flaggedCells.add(cell);
        return flaggedCells;
}
    1. Prevent misinformation => use proper conventions
    1. Make significative distinctions between concepts => don't use words that add superfluous noise to it. Names are easily distinguishable.
int caracterePreModification = ’a’;
int caracterePostModification = ’a’;
    1. Pronounceable names => Easy mental representation, easier communication.
class Customer {
    private Date modificationTimestamp;
    private final String recordId = "102";
}
    1. Searchable names => No magic numbers, use constants instead. No abbreviations, unless they are part of the business model. Use long enough names.
    1. No cryptic prefixes => Uniformity not matter the language.
    1. Explicit names => No mental associations, don't show off, no traduction should be needed.
  • 8.Verbs or nouns => classes = nouns, instances = nouns, variables = nouns, constants = uppercase nounds, methods = verbs
    1. Don't try to be funny
    1. 1 word equals 1 concept
    1. Don't use the same word for 2 things
    1. Use significative words from the domain
    1. Add a significative context
    1. Add context only if necessary

To resume

  • Name must be quickly comprehensible
  • Name must be clean and precise
  • Name must not lead to confusion
  • Name must have an evolution with what it represents
  • Name must be concise
⚠️ **GitHub.com Fallback** ⚠️