Komentar #

// ANTI-PATTERN: komentar yang hanya mengulang kode — tidak menambah nilai
int i = 0; // set i ke 0
i++;        // tambah i sebesar 1
return i;   // kembalikan i

// BENAR: komentar yang menjelaskan MENGAPA, bukan APA
// Mulai dari 0 karena indeks halaman berbasis 0 di API eksternal,
// tapi UI menampilkan dari halaman 1 — konversi dilakukan di sini.
int halaman = 0;
halaman++;
return halaman;

// ANTI-PATTERN: komentar kompensasi untuk nama yang buruk
// Fungsi ini menghitung x berdasarkan y dan z
double hitung(double y, double z) {
  return y * z * 0.1;
}

// BENAR: nama yang ekspresif menghilangkan kebutuhan komentar penjelasan
double hitungDiskon(double hargaAsli, double persentaseDiskon) {
  return hargaAsli * persentaseDiskon * 0.01;
}

// Komentar di baris tersendiri — untuk penjelasan sebelum blok kode
void prosesOrder(Order order) {
  // Validasi dilakukan sebelum menyentuh database agar tidak ada
  // data parsial yang tersimpan jika validasi gagal di tengah jalan.
  validasiOrder(order);

  // Simpan ke database
  simpanOrder(order);

  kirimEmail(order.email); // Notifikasi ke pelanggan setelah order tersimpan
}

// ✓ Menjelaskan keputusan non-obvious
// Gunakan ceiling bukan floor agar pengguna tidak merasa "dirugikan"
// saat jumlah tidak habis dibagi.
int jumlahHalaman = (totalItem / itemPerHalaman).ceil();

// ✓ Menandai bagian yang perlu perhatian khusus
// TODO: Ganti dengan cache setelah endpoint /v2/produk tersedia
List<Produk> produk = await apiLama.ambilProduk();

// ✓ Menjelaskan nilai magic number
const int batasRetry = 3;        // Standar industri untuk HTTP retry
const int timeoutDetik = 30;     // Batas maksimum dari SLA kontrak

// ✗ Jangan: komentar yang noise tanpa informasi baru
String nama = 'Budi'; // nama = 'Budi'
int umur = 25;         // umur adalah 25

// TODO: Implementasikan pagination sebelum rilis ke production
List<Produk> semuaProduk = await repository.ambilSemua();

// FIXME: Ada kondisi race ketika dua request datang bersamaan —
// perlu mutex atau atomic operation di sini.
stok -= jumlahPesan;

// HACK: Workaround untuk bug di library pihak ketiga versi 2.1.0
// Hapus ini setelah mereka merilis patch — lihat issue #4521
response = response.copyWith(headers: {'Content-Type': 'application/json'});

// DEPRECATED: Gunakan hitungDiskonV2() yang sudah mendukung diskon bertingkat
double hitungDiskon(double harga) => harga * 0.1;

/*
  Ini komentar multi-baris standar.
  Bisa mencakup berapa baris pun yang diperlukan.
  Dart juga mendukung nested block comment seperti ini:
  /*
    Ini nested comment — valid di Dart, tidak valid di C/Java.
  */
  Kembali ke komentar luar.
*/

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

  /*
  // Kode lama yang sedang dibandingkan performanya:
  var hasil = prosesLambat(data);
  print('Metode lama: ${stopwatch.elapsedMilliseconds}ms');
  */

  // Metode baru yang sedang diuji:
  var hasil = prosesCepat(data);
  print('Metode baru: ${stopwatch.elapsedMilliseconds}ms');
}

/*
  Blok ini dinonaktifkan sementara untuk A/B testing.
  Di dalamnya ada komentar multi-baris lain:
  /*
    Catatan tentang algoritma sebelumnya.
  */
  Dan ini tetap bagian dari komentar luar — valid di Dart.
*/

// ANTI-PATTERN: menggunakan /* */ untuk dokumentasi fungsi/kelas
/*
  Menghitung luas lingkaran.
  Parameter: radius — jari-jari lingkaran.
*/
double hitungLuasLingkaran(double radius) {
  return 3.14159 * radius * radius;
}
// Komentar ini tidak akan diproses oleh dart doc — tidak muncul di dokumentasi

// BENAR: gunakan /// untuk dokumentasi yang akan diproses tooling
/// Menghitung luas lingkaran berdasarkan jari-jari yang diberikan.
///
/// [radius] adalah jari-jari lingkaran dalam satuan meter.
/// Mengembalikan luas dalam meter persegi.
double hitungLuasLingkaran(double radius) {
  return 3.14159 * radius * radius;
}

/// Menghitung nilai diskon berdasarkan harga asli dan persentase.
///
/// Fungsi ini mengikuti aturan pembulatan ke atas (ceiling) agar
/// hasil diskon tidak pernah melebihi nilai yang seharusnya.
///
/// Contoh penggunaan:
/// ```dart
/// double diskon = hitungDiskon(150000, 20);
/// print(diskon); // 30000.0
/// ```
///
/// Parameter:
/// - [hargaAsli] — harga sebelum diskon, harus bernilai positif
/// - [persentase] — nilai diskon dalam persen (0–100)
///
/// Throws [ArgumentError] jika [hargaAsli] atau [persentase] negatif.
/// Returns nilai diskon dalam satuan yang sama dengan [hargaAsli].
double hitungDiskon(double hargaAsli, double persentase) {
  if (hargaAsli < 0) throw ArgumentError('hargaAsli tidak boleh negatif');
  if (persentase < 0 || persentase > 100) {
    throw ArgumentError('persentase harus antara 0 dan 100');
  }
  return hargaAsli * persentase / 100;
}

/// Merepresentasikan produk dalam katalog toko.
///
/// [Produk] menyimpan informasi dasar produk dan menyediakan
/// method untuk operasi umum seperti pengecekan ketersediaan stok
/// dan perhitungan harga setelah diskon.
///
/// Contoh penggunaan:
/// ```dart
/// var produk = Produk(
///   id: 'P001',
///   nama: 'Laptop Gaming',
///   harga: 15000000,
///   stok: 5,
/// );
///
/// if (produk.tersedia) {
///   print('Harga setelah diskon: ${produk.hargaSetelahDiskon(10)}');
/// }
/// ```
class Produk {
  /// Identifikasi unik produk dalam sistem.
  ///
  /// Format: huruf kapital diikuti angka, contoh `P001`, `PRD-042`.
  final String id;

  /// Nama produk yang ditampilkan ke pelanggan.
  String nama;

  /// Harga produk dalam Rupiah tanpa pajak.
  double harga;

  /// Jumlah unit yang tersedia di gudang.
  ///
  /// Nilai negatif tidak diizinkan — gunakan [tambahStok] dan
  /// [kurangiStok] untuk memodifikasinya dengan validasi otomatis.
  int stok;

  /// Membuat instance [Produk] baru.
  ///
  /// [id] dan [nama] wajib diisi. [stok] default ke 0 jika tidak diberikan.
  Produk({
    required this.id,
    required this.nama,
    required this.harga,
    this.stok = 0,
  });

  /// Mengembalikan `true` jika produk masih tersedia (stok > 0).
  bool get tersedia => stok > 0;

  /// Menghitung harga setelah potongan diskon.
  ///
  /// [diskonPersen] adalah persentase diskon (0–100).
  /// Throws [ArgumentError] jika nilai diskon di luar rentang yang valid.
  double hargaSetelahDiskon(double diskonPersen) {
    if (diskonPersen < 0 || diskonPersen > 100) {
      throw ArgumentError('diskonPersen harus antara 0 dan 100');
    }
    return harga * (1 - diskonPersen / 100);
  }

  /// Menambah stok produk sebanyak [jumlah].
  ///
  /// Throws [ArgumentError] jika [jumlah] tidak positif.
  void tambahStok(int jumlah) {
    if (jumlah <= 0) throw ArgumentError('jumlah harus lebih dari 0');
    stok += jumlah;
  }
}

/// Status pemrosesan sebuah order dari dibuat hingga selesai.
///
/// Urutan status normal: [menunggu] → [diproses] → [dikirim] → [selesai].
/// Status [dibatalkan] bisa terjadi dari [menunggu] atau [diproses].
enum StatusOrder {
  /// Order baru dibuat, belum diproses oleh tim gudang.
  menunggu,

  /// Order sedang disiapkan di gudang.
  diproses,

  /// Order sudah diserahkan ke kurir, dalam perjalanan.
  dikirim,

  /// Order sudah diterima pelanggan dan transaksi selesai.
  selesai,

  /// Order dibatalkan — bisa oleh pelanggan atau sistem.
  dibatalkan,
}

/// Mengambil produk berdasarkan ID dari repository.
///
/// Gunakan [ProdukRepository.ambilSemua] jika kamu butuh daftar lengkap.
/// Kembalikan [Produk] jika ditemukan, atau `null` jika tidak ada.
///
/// Lihat juga [CacheService] untuk strategi caching yang direkomendasikan.
Future<Produk?> ambilProduk(String id);

/// Memformat angka sebagai mata uang Rupiah.
///
/// Contoh:
/// ```dart
/// print(formatRupiah(150000));    // Rp 150.000
/// print(formatRupiah(1500000.5)); // Rp 1.500.001 (dibulatkan ke atas)
/// ```
///
/// Untuk format internasional, gunakan [NumberFormat] dari package `intl`.
String formatRupiah(double jumlah) {
  // implementasi
}

/// Membagi dua bilangan.
///
/// @param pembilang bilangan yang dibagi
/// @param penyebut bilangan pembagi, tidak boleh nol
/// @returns hasil pembagian sebagai double
/// @throws [ArgumentError] jika penyebut adalah nol
double bagi(double pembilang, double penyebut) {
  if (penyebut == 0) throw ArgumentError('penyebut tidak boleh nol');
  return pembilang / penyebut;
}

/// Membagi dua bilangan.
///
/// [pembilang] adalah angka yang ingin dibagi.
/// [penyebut] tidak boleh nol — throws [ArgumentError] jika nol.
/// Mengembalikan hasil pembagian sebagai [double].
double bagi(double pembilang, double penyebut) {
  if (penyebut == 0) throw ArgumentError('penyebut tidak boleh nol');
  return pembilang / penyebut;
}

/// Menghitung diskon sederhana.
///
/// **Deprecated:** Gunakan [hitungDiskonV2] yang mendukung diskon bertingkat.
/// Fungsi ini akan dihapus di versi 3.0.0.
@Deprecated('Gunakan hitungDiskonV2() — akan dihapus di v3.0.0')
double hitungDiskon(double harga) => harga * 0.1;

/// Menghitung diskon dengan dukungan diskon bertingkat.
///
/// Menggantikan [hitungDiskon] dengan kemampuan tambahan:
/// diskon bisa berbeda per kategori produk.
double hitungDiskonV2(double harga, {double persentase = 10}) {
  return harga * persentase / 100;
}

# Jalankan dari root direktori project
dart doc

# Dokumentasi dihasilkan di folder doc/api/
# Buka di browser:
open doc/api/index.html        # macOS
xdg-open doc/api/index.html    # Linux
start doc/api/index.html       # Windows

dartdoc:
  # Halaman tambahan (changelog, contributing guide, dll.)
  categories:
    "Panduan":
      markdown: doc/panduan.md
      name: "Panduan Penggunaan"

  # Exclude file/folder tertentu dari dokumentasi
  exclude:
    - "lib/src/internal/**"

  # Nama package yang ditampilkan
  name: "MyApp API Documentation"

# Lihat semua opsi yang tersedia
dart doc --help

// ANTI-PATTERN: komentar sudah tidak sesuai kode setelah refactoring
// Menghitung diskon 10%
double diskon = harga * 0.15; // kode sudah diubah ke 15% tapi komentar lupa diupdate

// BENAR: jika logika sudah jelas dari kode, hapus komentar sama sekali
double diskon = harga * PERSENTASE_DISKON; // nama konstanta sudah cukup jelas

// ANTI-PATTERN: kode lama yang "mungkin nanti diperlukan" dikomentari bertahun-tahun
// var hasil = metodeLama(input);
// print('debug: $hasil');
// if (hasil > threshold) return;
var hasil = metodeBar(input);

// BENAR: hapus kode yang tidak dipakai — version control (Git) menyimpan riwayatnya
// Jika kamu takut kehilangan kode lama, tambahkan tag Git atau catatan commit
var hasil = metodeBaru(input);

// ANTI-PATTERN: mendokumentasikan detail implementasi private yang sering berubah
class _KeranjangBelanjaState extends State<KeranjangBelanja> {
  /// List internal yang menyimpan item dalam keranjang.
  /// Diinisialisasi sebagai list kosong dan diisi saat pengguna menambahkan produk.
  /// Tidak boleh diakses langsung dari luar kelas.
  List<Item> _items = [];  // private, tidak perlu DartDoc

  // BENAR: dokumentasi DartDoc hanya untuk API publik
  // Variabel private cukup dengan // jika memang perlu komentar
  List<Item> _items = []; // cache lokal, di-sync dengan CartRepository
}

// ANTI-PATTERN: blok komentar besar sebagai "header file" gaya C
//===========================================================
// File: produk_repository.dart
// Author: Budi Santoso
// Date: 2024-01-15
// Description: Repository untuk operasi CRUD produk
// Version: 1.0.0
//===========================================================

// BENAR: informasi ini sudah ada di Git history dan pubspec.yaml
// Mulai langsung dengan kode atau DartDoc kelas