Encapsulation in Dart

This is Part 3 of the Object-Oriented Dart series. We've built classes (Part 1) and learned every way to construct them (Part 2). Now we meet the first of OOP's four pillars: encapsulation.

Encapsulation is the discipline of hiding an object's internal details and exposing only a safe, deliberate surface. Think of a vending machine: you press buttons and money goes in, a drink comes out. You can't reach inside and rearrange the coils or short the wiring. The complexity is sealed away behind a small, well-defined interface. That's encapsulation, and Dart gives you clean tools for it.

Why bother hiding anything?

Imagine a BankAccount with a fully public balance:

class BankAccount {
  double balance = 0;
}

void main() {
  var acc = BankAccount();
  acc.balance = -9999; // 😱 nothing stopped this
}

Any code anywhere can set the balance to nonsense. There's no validation, no logging, no way to enforce "balance can't go negative." The object can't protect its own correctness — its invariants (the rules that must always hold) are at the mercy of every caller.

Encapsulation fixes this by making the raw data private and forcing all access to go through methods (or getters/setters) that you control. The object becomes responsible for keeping itself valid.

Privacy in Dart: the underscore

Most languages use keywords like private and public. Dart doesn't. Instead it has one simple rule:

An identifier that starts with an underscore (_) is private to its library.

A "library" in Dart is, by default, a single .dart file (until you start using part/part of, which is rare). So _balance is visible everywhere inside the same file and invisible to any other file that imports it.

class BankAccount {
  double _balance = 0; // private — not visible outside this file

  void deposit(double amount) {
    if (amount <= 0) throw ArgumentError('Deposit must be positive');
    _balance += amount;
  }

  double get balance => _balance; // read-only window
}

Now external code cannot write acc._balance = -9999 — the field doesn't even exist as far as another file is concerned. The only ways in are deposit() and the read-only balance getter, both of which you control.

The "library, not class" gotcha. Privacy is per library (file), not per class. Two classes written in the same file can freely read each other's _private members. That surprises people coming from Java. It's also genuinely useful — it lets a small cluster of tightly-related classes cooperate in one file while staying sealed off from the outside world.

Getters and setters: computed properties

You've already seen double get balance => _balance;. Let's name what that is.

A getter is a method that's called like a field — no parentheses. A setter is the same idea for assignment. They let you expose a clean property-style surface while running real logic behind the scenes. The magic: you can start with a plain public field and later upgrade it to a getter/setter without changing a single line of caller code.

A read-only property

The simplest use is exposing private data for reading only — provide a getter, no setter:

class Temperature {
  double _celsius;
  Temperature(this._celsius);

  double get celsius => _celsius;          // read-only
  double get fahrenheit => _celsius * 9 / 5 + 32; // fully computed
}

void main() {
  var t = Temperature(25);
  print(t.celsius);    // 25.0   — looks like a field, is a getter
  print(t.fahrenheit); // 77.0   — computed on the fly, stored nowhere
}

fahrenheit isn't stored anywhere — it's derived every time you read it. Callers can't tell the difference between a stored field and a computed getter, and that's the point.

A validating setter

Pair a getter with a setter to intercept writes and enforce rules:

class Temperature {
  double _celsius;
  Temperature(this._celsius);

  double get celsius => _celsius;

  set celsius(double value) {
    if (value < -273.15) {
      throw ArgumentError('Below absolute zero!');
    }
    _celsius = value;
  }

  // A computed property with BOTH getter and setter:
  double get fahrenheit => _celsius * 9 / 5 + 32;
  set fahrenheit(double f) => _celsius = (f - 32) * 5 / 9;
}

void main() {
  var t = Temperature(25);
  t.fahrenheit = 212; // looks like assignment, runs conversion
  print(t.celsius);   // 100.0
}

Look at that last bit: writing t.fahrenheit = 212 feels like setting a field, but it actually runs your conversion and updates _celsius. The caller gets a clean, intuitive API and you keep full control. This is encapsulation at its most elegant.

Why not just use a method like setFahrenheit(212)? You could! Getters/setters are mostly about ergonomics — they let a value read and write like a property (t.fahrenheit) instead of a function call (t.getFahrenheit()). Reach for a getter when something conceptually is a property; reach for a method when it conceptually does an action.

final and late fields

Encapsulation isn't only about privacy — it's also about controlling when and whether a field can change.

final fields — set once

A final field can be assigned exactly once, during construction, and never again. It's the simplest way to make part of an object immutable:

class Profile {
  final String username;     // can never change after construction
  final DateTime createdAt = DateTime.now(); // set at declaration

  Profile(this.username);
}

A final field gets an implicit getter but no setter — so it's automatically read-only to the outside world, no underscore needed. Prefer final for anything that shouldn't change after an object is built; it eliminates a whole class of bugs.

late fields — deferred initialization

Sometimes a non-nullable field genuinely can't be set at construction time — maybe it depends on something computed later. Marking it late tells Dart "I promise to assign this before anyone reads it":

class Report {
  late final String _summary; // assigned later, but only once

  void build(List<String> lines) {
    _summary = lines.join('\n'); // first read of _summary is now valid
  }
}

late has two superpowers:

1. It lets a non-nullable field skip initialization at the declaration/constructor — Dart trusts you to set it first. (Read it before assigning and you get a clear runtime error, not a silent null.)
2. late + an initializer = lazy evaluation. The initializer runs only on first access:

class Service {
  late final _connection = _expensiveSetup(); // runs on first use, not before
}

If nothing ever touches _connection, _expensiveSetup() never runs. Great for expensive resources you might not need.

Careful with late: it trades a compile-time guarantee for a runtime one. If you read a plain late field before assigning it, you get a LateInitializationError at runtime. Use it deliberately, not to silence the null checker.

Static members: state that belongs to the class

Everything so far has been instance state — each object has its own copy. Sometimes, though, data or behavior belongs to the class itself, shared across all instances. That's what static is for.

Static variables (class-wide state)

class Player {
  static int count = 0; // ONE shared counter for the whole class
  final String name;

  Player(this.name) {
    count++; // every new player bumps the shared count
  }
}

void main() {
  Player('A');
  Player('B');
  print(Player.count); // 2 — accessed on the CLASS, not an instance
}

There's exactly one count, no matter how many Players exist. You access it via the class name (Player.count), never via an instance. Static fields are also lazily initialized — they don't exist until first used.

Static constants

static const is the idiomatic home for class-level constants:

class Circle {
  static const double pi = 3.14159;
  final double radius;
  Circle(this.radius);

  double get area => pi * radius * radius;
}

Static methods

A static method belongs to the class, not an instance — so it has no this and can't touch instance fields. It's perfect for utility functions that relate to the type but don't need a particular object:

import 'dart:math';

class Point {
  final double x, y;
  const Point(this.x, this.y);

  // Doesn't need a specific point — operates on two given points.
  static double distance(Point a, Point b) {
    final dx = a.x - b.x;
    final dy = a.y - b.y;
    return sqrt(dx * dx + dy * dy);
  }
}

void main() {
  final d = Point.distance(const Point(0, 0), const Point(3, 4));
  print(d); // 5.0
}

Instance vs. static, in one line: instance members need a specific object to make sense (order.describe() — which order?). Static members make sense without any object (Point.distance(a, b), Player.count).

Putting it together: a self-protecting class

Here's a BankAccount that fully encapsulates its state — invalid states are simply unreachable from outside:

class BankAccount {
  final String owner;
  double _balance;
  final List<String> _log = [];

  BankAccount(this.owner, {double openingBalance = 0})
      : _balance = openingBalance;

  double get balance => _balance;            // read-only
  List<String> get history => List.unmodifiable(_log); // defensive copy

  void deposit(double amount) {
    if (amount <= 0) throw ArgumentError('Deposit must be positive');
    _balance += amount;
    _log.add('Deposited $amount');
  }

  void withdraw(double amount) {
    if (amount <= 0) throw ArgumentError('Withdrawal must be positive');
    if (amount > _balance) throw StateError('Insufficient funds');
    _balance -= amount;
    _log.add('Withdrew $amount');
  }
}

Notice history returns List.unmodifiable(_log) — a defensive copy. If we returned _log directly, a caller could do acc.history.clear() and erase our audit trail. Encapsulation isn't just about the fields; it's about not leaking mutable references to your internals either. This is a subtle, important habit.

Practice Challenges

Challenge 1 — Make it private. Take this leaky class and encapsulate score so it can only be increased, never set directly or made negative.

class Game {
  int score = 0;
}

class Game {
  int _score = 0;

  int get score => _score; // read-only

  void addPoints(int points) {
    if (points < 0) throw ArgumentError('points must be non-negative');
    _score += points;
  }
}

Challenge 2 — Computed getter. Add a Rectangle class with width and height, plus read-only area and perimeter getters.

class Rectangle {
  final double width;
  final double height;
  const Rectangle(this.width, this.height);

  double get area => width * height;
  double get perimeter => 2 * (width + height);
}

void main() {
  const r = Rectangle(3, 4);
  print(r.area);      // 12.0
  print(r.perimeter); // 14.0
}

Challenge 3 — Getter + setter pair. Give a Person a private _age, a getter, and a setter that rejects negative ages.

class Person {
  int _age;
  Person(this._age);

  int get age => _age;

  set age(int value) {
    if (value < 0) throw ArgumentError('age cannot be negative');
    _age = value;
  }
}

void main() {
  var p = Person(30);
  p.age = 31;        // goes through the setter
  print(p.age);      // 31
  // p.age = -5;     // would throw
}

Challenge 4 — Static counter. Track how many Widget objects have been created, exposed as a read-only class-level count.

class Widget {
  static int _count = 0;
  static int get count => _count;

  Widget() {
    _count++;
  }
}

void main() {
  Widget();
  Widget();
  Widget();
  print(Widget.count); // 3
}

Challenge 5 — Lazy late. Create a Config class whose settings map is loaded by an expensive function that should run only on first access, and never if settings is never read.

class Config {
  late final Map<String, String> settings = _load();

  Map<String, String> _load() {
    print('Loading config...'); // proof it runs lazily
    return {'theme': 'dark'};
  }
}

void main() {
  var c = Config();
  print('Config created'); // "Loading config..." has NOT printed yet
  print(c.settings);        // now "Loading config..." prints, then the map
}

Challenge 6 — Don't leak internals. A Team holds a private List<String> _members. Expose the members for reading without letting callers mutate the internal list.

class Team {
  final List<String> _members = [];

  List<String> get members => List.unmodifiable(_members);

  void add(String name) => _members.add(name);
}

void main() {
  var t = Team()..add('Sam')..add('Alex');
  print(t.members);       // [Sam, Alex]
  // t.members.add('Eve'); // throws — the returned list is unmodifiable
}

Questions to test yourself

Q1 (basic). How do you make a field private in Dart?

Q2 (basic). What's the difference between a getter and a regular method?

Q3 (intermediate). Two classes A and B are in the same .dart file. Can A read B's _secret field? What if they're in different files?

Q4 (intermediate). You expose a list via List<String> get tags => _tags;. Why is this a subtle encapsulation leak, and how do you fix it?

Q5 (advanced). What's the practical difference between final and late final for a field, and what new failure mode does late introduce?

Q6 (advanced). A static method can't access instance fields or this. Why not, and what does that tell you about when to make a method static?

Wrapping up

Encapsulation is the habit that keeps objects trustworthy:

• Underscore (_) makes members private to their library/file — Dart's only access control.
• Getters and setters expose a clean property surface while you keep control of reads, writes, and computed values.
• final makes a field write-once (and read-only to the outside); late defers initialization and can make it lazy.
• static members belong to the class itself — shared state, constants, and utility methods with no this.
• Don't leak mutable references to internals — return unmodifiable views or copies.

In Part 4 we round out an object's surface with methods, operator overloading, and cascades — including how to make == mean what you actually want it to mean.