The Principle of Least Astonishment (POLA)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

// ❌ Convention violations that astonish
 
class UserRepository {
  // 'get' implies no side effects, but this modifies lastAccessTime
  getUser(id: string): User {
    const user = this.db.find(id);
    user.lastAccessTime = Date.now();  // Side effect!
    return user;
  }
  
  // 'is' implies cheap boolean, but this makes network call
  async isUserActive(id: string): Promise<boolean> {
    const response = await fetch(`/api/users/${id}/status`);
    return response.json().active;  // Network call!
  }
  
  // 'create' implies new instance, but this returns cached instance
  createLogger(name: string): Logger {
    if (this.loggers.has(name)) {
      return this.loggers.get(name);  // Not creating!
    }
    const logger = new Logger(name);
    this.loggers.set(name, logger);
    return logger;
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

// ✅ Respecting conventions
 
class UserRepository {
  // Read-only: matches 'get' convention
  getUser(id: string): User {
    return this.db.find(id);
  }
  
  // Side effect: name reflects it
  getUserAndRecordAccess(id: string): User {
    const user = this.db.find(id);
    user.lastAccessTime = Date.now();
    return user;
  }
  
  // Async and potentially slow: name reflects it
  async checkIsUserActive(id: string): Promise<boolean> {
    const response = await fetch(`/api/users/${id}/status`);
    return response.json().active;
  }
  
  // May return cached: name reflects it
  getOrCreateLogger(name: string): Logger {
    if (this.loggers.has(name)) {
      return this.loggers.get(name);
    }
    const logger = new Logger(name);
    this.loggers.set(name, logger);
    return logger;
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

// ❌ Temporal confusion
 
class EmailService {
  // Does this send immediately or queue?
  send(email: Email): void {
    this.queue.add(email);  // Surprise! Doesn't send immediately
  }
  
  // Does this block until message is received?
  receiveMessage(): Message {
    return this.blockingQueue.take();  // Surprise! Blocks forever
  }
}
 
// ✅ Temporal clarity
 
class EmailService {
  // Name clarifies: queued, not sent
  queueForDelivery(email: Email): void {
    this.queue.add(email);
  }
  
  // Name clarifies: sends immediately, async
  async sendImmediately(email: Email): Promise<DeliveryResult> {
    return await this.smtpClient.send(email);
  }
  
  // Name clarifies: blocking operation
  receiveMessageBlocking(): Message {
    return this.blockingQueue.take();
  }
  
  // Name clarifies: non-blocking, may not have message
  tryReceiveMessage(): Message | null {
    return this.queue.poll();
  }
  
  // Name clarifies: async with timeout
  async receiveMessageAsync(timeout: Duration): Promise<Message | null> {
    return await this.queue.pollAsync(timeout);
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

// ❌ Parameter naming that causes bugs
 
function schedule(
  callback: () => void,
  time: number  // Seconds? Milliseconds? Absolute time?
): void;
 
function copy(
  src: string,   // Source or destination first?
  dst: string
): void;
 
function between(
  a: number,     // Inclusive? Exclusive?
  b: number,
  value: number  // Is value the thing being tested or a bound?
): boolean;
 
 
// ✅ Parameter naming that prevents bugs
 
function scheduleAfterMs(
  callback: () => void,
  delayMilliseconds: number
): CancellationToken;
 
function copyFromTo(
  sourcePath: string,
  destinationPath: string,
  options?: CopyOptions
): Promise<void>;
 
function isValueBetween(
  value: number,
  lowerBoundInclusive: number,
  upperBoundExclusive: number
): boolean;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

// ❌ Vague class names
 
class UserHelper {
  validate(user: User): boolean;
  format(user: User): string;
  sendEmail(user: User, template: string): void;
  checkPermissions(user: User, resource: Resource): boolean;
  // What is this class's responsibility? Everything?
}
 
class DataProcessor {
  process(data: unknown): unknown;  // What does this even do?
}
 
 
// ✅ Focused, intention-revealing names
 
class UserValidator {
  validate(user: User): ValidationResult;
}
 
class UserProfileFormatter {
  formatForDisplay(user: User): FormattedProfile;
  formatForExport(user: User): ExportableProfile;
}
 
class WelcomeEmailSender {
  sendWelcomeEmail(user: User): Promise<DeliveryStatus>;
}
 
class ResourceAccessChecker {
  canAccess(user: User, resource: Resource): boolean;
  getAccessibleResources(user: User): Resource[];
}