Code Documentation

Explicitly document no operations

On occasions, some code might simply do nothing at all, these scenarios are usually referred to as no operations (no-op). The reasons for the need to introduce a no-op may vary. For example, it could well be due to the need to align with an interface.

Leaving the no-operation without an explanatory comment may cause engineers to doubt whether the code was left uncompleted intentionally or not. If there is a need for a no-op, document its existence.

The same principle would apply if a comment left is not clear enough.

Good ✅

class BluetoothProcessor extends NetworkProcessor {
  @override
  void abort() {
      // Intentional no-op, an abort in Bluetooth has no resources to clean.
  }
}

Bad ❗️

class BluetoothProcessor extends NetworkProcessor {
  @override
  void abort() {}
}