Comments #

// ANTI-PATTERN: a comment that only repeats the code — adds no value
int i = 0; // set i to 0
i++;        // increment i by 1
return i;   // return i

// CORRECT: a comment that explains WHY, not WHAT
// Start at 0 because the external API uses zero-based page indices,
// but the UI displays from page 1 — the conversion happens here.
int halaman = 0;
halaman++;
return halaman;

// ANTI-PATTERN: compensation comments for bad names
// This function calculates x based on y and z
double hitung(double y, double z) {
  return y * z * 0.1;
}

// CORRECT: expressive names remove the need for explanatory comments
double hitungDiskon(double hargaAsli, double persentaseDiskon) {
  return hargaAsli * persentaseDiskon * 0.01;
}

// Comment on its own line — for an explanation before a block of code
void prosesOrder(Order order) {
  // Validation happens before touching the database so no partial
  // data is stored if validation fails halfway through.
  validasiOrder(order);

  // Save to the database
  simpanOrder(order);

  kirimEmail(order.email); // Notify the customer after the order is saved
}

// ✓ Explaining a non-obvious decision
// Use ceiling instead of floor so users don't feel "shortchanged"
// when the count doesn't divide evenly.
int jumlahHalaman = (totalItem / itemPerHalaman).ceil();

// ✓ Marking areas that need special attention
// TODO: Replace with a cache once the /v2/produk endpoint is available
List<Produk> produk = await apiLama.ambilProduk();

// ✓ Explaining magic number values
const int batasRetry = 3;        // Industry standard for HTTP retries
const int timeoutDetik = 30;     // Maximum limit from the contract SLA

// ✗ Don't: noise comments without any new information
String nama = 'Budi'; // nama = 'Budi'
int umur = 25;         // umur is 25

// TODO: Implement pagination before releasing to production
List<Produk> semuaProduk = await repository.ambilSemua();

// FIXME: There's a race condition when two requests arrive at the same time —
// a mutex or atomic operation is needed here.
stok -= jumlahPesan;

// HACK: Workaround for a bug in the third-party library version 2.1.0
// Remove this once they ship a patch — see issue #4521
response = response.copyWith(headers: {'Content-Type': 'application/json'});

// DEPRECATED: Use hitungDiskonV2() which already supports tiered discounts
double hitungDiskon(double harga) => harga * 0.1;

/*
  This is a standard multi-line comment.
  It can span as many lines as needed.
  Dart also supports nested block comments like this:
  /*
    This is a nested comment — valid in Dart, not valid in C/Java.
  */
  Back to the outer comment.
*/

void main() {
  var data = ambilData();

  /*
  // Old code being compared for performance:
  var hasil = prosesLambat(data);
  print('Old method: ${stopwatch.elapsedMilliseconds}ms');
  */

  // New method being tested:
  var hasil = prosesCepat(data);
  print('New method: ${stopwatch.elapsedMilliseconds}ms');
}

/*
  This block is temporarily disabled for A/B testing.
  Inside it there's another multi-line comment:
  /*
    Notes about the previous algorithm.
  */
  And this is still part of the outer comment — valid in Dart.
*/

// ANTI-PATTERN: using /* */ to document functions/classes
/*
  Calculates the area of a circle.
  Parameter: radius — the circle's radius.
*/
double hitungLuasLingkaran(double radius) {
  return 3.14159 * radius * radius;
}
// This comment won't be processed by dart doc — it won't appear in the docs

// CORRECT: use /// for documentation that gets processed by tooling
/// Calculates the area of a circle from the given radius.
///
/// [radius] is the circle's radius in meters.
/// Returns the area in square meters.
double hitungLuasLingkaran(double radius) {
  return 3.14159 * radius * radius;
}

/// Calculates the discount value from the original price and percentage.
///
/// This function rounds up (ceiling) so the discount result
/// never exceeds the expected value.
///
/// Example usage:
/// ```dart
/// double diskon = hitungDiskon(150000, 20);
/// print(diskon); // 30000.0
/// ```
///
/// Parameters:
/// - [hargaAsli] — the price before discount, must be positive
/// - [persentase] — the discount value in percent (0–100)
///
/// Throws [ArgumentError] if [hargaAsli] or [persentase] is negative.
/// Returns the discount value in the same unit as [hargaAsli].
double hitungDiskon(double hargaAsli, double persentase) {
  if (hargaAsli < 0) throw ArgumentError('hargaAsli cannot be negative');
  if (persentase < 0 || persentase > 100) {
    throw ArgumentError('persentase must be between 0 and 100');
  }
  return hargaAsli * persentase / 100;
}

/// Represents a product in the store catalog.
///
/// [Produk] stores basic product information and provides
/// methods for common operations like checking stock availability
/// and calculating prices after discounts.
///
/// Example usage:
/// ```dart
/// var produk = Produk(
///   id: 'P001',
///   nama: 'Gaming Laptop',
///   harga: 15000000,
///   stok: 5,
/// );
///
/// if (produk.tersedia) {
///   print('Price after discount: ${produk.hargaSetelahDiskon(10)}');
/// }
/// ```
class Produk {
  /// Unique product identifier in the system.
  ///
  /// Format: capital letter followed by digits, e.g. `P001`, `PRD-042`.
  final String id;

  /// Product name displayed to customers.
  String nama;

  /// Product price in Rupiah, excluding tax.
  double harga;

  /// Number of units available in the warehouse.
  ///
  /// Negative values are not allowed — use [tambahStok] and
  /// [kurangiStok] to modify it with automatic validation.
  int stok;

  /// Creates a new [Produk] instance.
  ///
  /// [id] and [nama] are required. [stok] defaults to 0 if not provided.
  Produk({
    required this.id,
    required this.nama,
    required this.harga,
    this.stok = 0,
  });

  /// Returns `true` if the product is still available (stok > 0).
  bool get tersedia => stok > 0;

  /// Calculates the price after a discount.
  ///
  /// [diskonPersen] is the discount percentage (0–100).
  /// Throws [ArgumentError] if the discount value is outside the valid range.
  double hargaSetelahDiskon(double diskonPersen) {
    if (diskonPersen < 0 || diskonPersen > 100) {
      throw ArgumentError('diskonPersen must be between 0 and 100');
    }
    return harga * (1 - diskonPersen / 100);
  }

  /// Adds [jumlah] to the product's stock.
  ///
  /// Throws [ArgumentError] if [jumlah] is not positive.
  void tambahStok(int jumlah) {
    if (jumlah <= 0) throw ArgumentError('jumlah must be greater than 0');
    stok += jumlah;
  }
}

/// The processing status of an order from creation to completion.
///
/// Normal status flow: [menunggu] → [diproses] → [dikirim] → [selesai].
/// The [dibatalkan] status can happen from [menunggu] or [diproses].
enum StatusOrder {
  /// Order just created, not yet processed by the warehouse team.
  menunggu,

  /// Order is being prepared in the warehouse.
  diproses,

  /// Order has been handed to the courier, in transit.
  dikirim,

  /// Order has been received by the customer and the transaction is complete.
  selesai,

  /// Order canceled — either by the customer or the system.
  dibatalkan,
}

/// Fetches a product by ID from the repository.
///
/// Use [ProdukRepository.ambilSemua] if you need the full list.
/// Returns a [Produk] if found, or `null` if it doesn't exist.
///
/// See also [CacheService] for recommended caching strategies.
Future<Produk?> ambilProduk(String id);

/// Formats a number as Rupiah currency.
///
/// Example:
/// ```dart
/// print(formatRupiah(150000));    // Rp 150.000
/// print(formatRupiah(1500000.5)); // Rp 1.500.001 (rounded up)
/// ```
///
/// For international formats, use [NumberFormat] from the `intl` package.
String formatRupiah(double jumlah) {
  // implementation
}

/// Divides two numbers.
///
/// @param pembilang the number being divided
/// @param penyebut the divisor, must not be zero
/// @returns the division result as a double
/// @throws [ArgumentError] if penyebut is zero
double bagi(double pembilang, double penyebut) {
  if (penyebut == 0) throw ArgumentError('penyebut cannot be zero');
  return pembilang / penyebut;
}

/// Divides two numbers.
///
/// [pembilang] is the number you want to divide.
/// [penyebut] must not be zero — throws [ArgumentError] if zero.
/// Returns the division result as a [double].
double bagi(double pembilang, double penyebut) {
  if (penyebut == 0) throw ArgumentError('penyebut cannot be zero');
  return pembilang / penyebut;
}

/// Calculates a simple discount.
///
/// **Deprecated:** Use [hitungDiskonV2] which supports tiered discounts.
/// This function will be removed in version 3.0.0.
@Deprecated('Use hitungDiskonV2() — will be removed in v3.0.0')
double hitungDiskon(double harga) => harga * 0.1;

/// Calculates a discount with tiered discount support.
///
/// Replaces [hitungDiskon] with additional capabilities:
/// discounts can differ per product category.
double hitungDiskonV2(double harga, {double persentase = 10}) {
  return harga * persentase / 100;
}

# Run from the project root directory
dart doc

# Documentation is generated in the doc/api/ folder
# Open it in the browser:
open doc/api/index.html        # macOS
xdg-open doc/api/index.html    # Linux
start doc/api/index.html       # Windows

doc/
  └── api/
      ├── index.html            ← main page
      ├── produk/               ← one folder per library
      │   ├── Produk-class.html
      │   ├── StatusOrder.html
      │   └── ...
      └── ...

dartdoc:
  # Additional pages (changelog, contributing guide, etc.)
  categories:
    "Guide":
      markdown: doc/panduan.md
      name: "Usage Guide"

  # Exclude certain files/folders from documentation
  exclude:
    - "lib/src/internal/**"

  # Package name shown in the output
  name: "MyApp API Documentation"

# See all available options
dart doc --help

// ANTI-PATTERN: comment no longer matches the code after refactoring
// Calculates a 10% discount
double diskon = harga * 0.15; // code was changed to 15% but the comment wasn't updated

// CORRECT: if the logic is clear from the code, remove the comment entirely
double diskon = harga * PERSENTASE_DISKON; // the constant name is clear enough

// ANTI-PATTERN: old code that "might be needed later" commented out for years
// var hasil = metodeLama(input);
// print('debug: $hasil');
// if (hasil > threshold) return;
var hasil = metodeBar(input);

// CORRECT: delete unused code — version control (Git) keeps the history
// If you're afraid of losing old code, add a Git tag or a commit note
var hasil = metodeBaru(input);

// ANTI-PATTERN: documenting private implementation details that change often
class _KeranjangBelanjaState extends State<KeranjangBelanja> {
  /// Internal list that stores items in the cart.
  /// Initialized as an empty list and filled when the user adds products.
  /// Must not be accessed directly from outside the class.
  List<Item> _items = [];  // private, no DartDoc needed

  // CORRECT: DartDoc documentation is only for public APIs
  // Private variables only need // if a comment is really necessary
  List<Item> _items = []; // local cache, synced with CartRepository
}

// ANTI-PATTERN: big comment blocks as C-style "file headers"
//===========================================================
// File: produk_repository.dart
// Author: Budi Santoso
// Date: 2024-01-15
// Description: Repository for product CRUD operations
// Version: 1.0.0
//===========================================================

// CORRECT: this information already lives in Git history and pubspec.yaml
// Start directly with code or class DartDoc

WRITE A COMMENT when:
  ✓ The code does something counter-intuitive — explain why
  ✓ There's a workaround for an external library bug — include the issue number
  ✓ There's a debated design decision — record the reasoning
  ✓ There's a non-obvious constraint — e.g. "must be called after init()"
  ✓ You're documenting a public API — use ///
  ✓ There are TODO/FIXMEs that need follow-up

DON'T WRITE A COMMENT when:
  ✗ The code already reads clearly — function/variable names are enough
  ✗ The comment only repeats what the code does (noise)
  ✗ The comment explains code that should be refactored
  ✗ Documenting private properties/methods with DartDoc
  ✗ File header comments with information that's in Git