Komentar #

let batasPercobaan: number = 3;        // Batas sesuai kebijakan keamanan
let intervalKadaluarsa: number = 3600; // Dalam detik — 1 jam

// Mulai hitung dari 1, bukan 0, agar pesan error lebih natural untuk pengguna
for (let percobaan = 1; percobaan <= batasPercobaan; percobaan++) {
  console.log(`Percobaan ${percobaan} dari ${batasPercobaan}`);
}

// ANTI-PATTERN: Komentar yang hanya mengulang kode — tidak menambah informasi
const usia: number = 17; // Tetapkan usia ke 17
if (usia >= 18) {        // Periksa apakah usia lebih dari atau sama dengan 18
  console.log("Dewasa"); // Cetak "Dewasa"
}

// BENAR: Komentar yang menjelaskan alasan (the "why"), bukan aksi (the "what")
const usia: number = 17;
if (usia >= 18) {
  // Sesuai UU No. 35 Tahun 2014 — batas dewasa adalah 18 tahun
  console.log("Akses penuh diizinkan");
}

/*
  Algoritma ini menggunakan pendekatan sliding window untuk menghitung
  rata-rata bergerak. Kompleksitas waktu O(n), jauh lebih efisien dari
  pendekatan naive O(n²) yang menghitung ulang dari awal setiap iterasi.

  Referensi: https://en.wikipedia.org/wiki/Moving_average
*/
function rataRataBergerak(data: number[], ukuranWindow: number): number[] {
  const hasil: number[] = [];
  let jumlah = 0;

  for (let i = 0; i < data.length; i++) {
    jumlah += data[i];

    if (i >= ukuranWindow) {
      jumlah -= data[i - ukuranWindow];
    }

    if (i >= ukuranWindow - 1) {
      hasil.push(jumlah / ukuranWindow);
    }
  }

  return hasil;
}

function prosesData(input: string[]): string[] {
  const hasil = input.map((item) => item.trim().toLowerCase());

  /*
  // Normalisasi tambahan — dinonaktifkan sementara untuk investigasi bug #4521
  const hasilNormalisasi = hasil.map((item) => {
    return item.replace(/[^a-z0-9]/g, "-");
  });
  return hasilNormalisasi;
  */

  return hasil;
}

/**
 * Menghitung total harga setelah diskon dan pajak diterapkan.
 *
 * @param harga - Harga dasar produk dalam Rupiah
 * @param diskon - Persentase diskon (0–100). Default: 0
 * @param pajakPersen - Persentase pajak (0–100). Default: 11 (PPN)
 * @returns Total harga akhir setelah diskon dan pajak
 *
 * @example
 * ```typescript
 * hitungTotal(100000, 10, 11); // 99900 (diskon 10%, PPN 11%)
 * hitungTotal(50000);          // 55500 (tanpa diskon, PPN 11%)
 * ```
 */
function hitungTotal(
  harga: number,
  diskon: number = 0,
  pajakPersen: number = 11
): number {
  const setelahDiskon = harga * (1 - diskon / 100);
  const setelahPajak = setelahDiskon * (1 + pajakPersen / 100);
  return Math.round(setelahPajak);
}

/**
 * Representasi data produk dalam sistem e-commerce.
 * Digunakan untuk response API dan state di frontend.
 */
interface Produk {
  /** ID unik produk — format UUID v4 */
  id: string;

  /** Nama produk yang ditampilkan ke pengguna */
  nama: string;

  /** Harga dalam satuan Rupiah (IDR), bukan sen */
  harga: number;

  /** Jumlah stok yang tersedia. 0 berarti habis, -1 berarti tidak dilacak */
  stok: number;

  /** Kategori produk. Gunakan nilai dari enum KategoriProduk */
  kategori: string;

  /** Timestamp pembuatan dalam format ISO 8601 */
  dibuatPada: string;

  /** URL gambar utama produk. Opsional — bisa null jika belum ada gambar */
  gambarUrl?: string | null;
}

/**
 * Service untuk mengelola autentikasi pengguna.
 *
 * @remarks
 * Semua token disimpan di memory, bukan localStorage, untuk mencegah
 * serangan XSS. Token di-refresh otomatis 5 menit sebelum kadaluarsa.
 *
 * @example
 * ```typescript
 * const auth = new AuthService("https://api.example.com");
 * const token = await auth.masuk("[email protected]", "password");
 * ```
 */
class AuthService {
  private baseUrl: string;
  private tokenAktif: string | null = null;

  /**
   * Membuat instance AuthService baru.
   * @param baseUrl - Base URL API autentikasi (tanpa trailing slash)
   */
  constructor(baseUrl: string) {
    this.baseUrl = baseUrl;
  }

  /**
   * Melakukan autentikasi pengguna dan menyimpan token.
   *
   * @param email - Alamat email pengguna
   * @param password - Password pengguna (dikirim via HTTPS, tidak di-log)
   * @returns Token JWT jika berhasil
   * @throws {Error} Jika kredensial salah atau server tidak dapat dijangkau
   */
  async masuk(email: string, password: string): Promise<string> {
    const response = await fetch(`${this.baseUrl}/auth/login`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ email, password }),
    });

    if (!response.ok) {
      throw new Error(`Autentikasi gagal: ${response.status}`);
    }

    const data = await response.json();
    this.tokenAktif = data.token;
    return data.token;
  }
}

// @ts-ignore
const nilai: number = "ini bukan angka"; // Error biasanya muncul, tapi diabaikan

// ANTI-PATTERN: @ts-ignore diam-diam — tidak ada peringatan jika error sudah diperbaiki
// @ts-ignore
fungsiYangSudahDiperbaiki(argumenBenar); // Jika sudah benar, @ts-ignore "nganggur" tanpa peringatan

// BENAR: @ts-expect-error — compiler komplain jika error tidak terjadi
// @ts-expect-error: Sengaja tes dengan tipe yang salah untuk validasi runtime error handling
fungsiDenganValidasi("bukan-angka");

// @ts-nocheck
// File ini adalah migrasi dari JavaScript — type checking dinonaktifkan sementara
// TODO: Hapus @ts-nocheck setelah migrasi selesai (target: Sprint 24)

const data = ambilData();
prosesData(data.apapun.tanpa.tipe);

// @ts-check
// File JavaScript biasa, tapi mendapat type checking dari TypeScript

/**
 * @param {string} nama
 * @param {number} usia
 * @returns {string}
 */
function buatBio(nama, usia) {
  return `${nama}, ${usia} tahun`;
}

buatBio("Budi", 25); // ✓
// buatBio(123, "dua puluh lima"); // ✗ TypeScript akan melaporkan error

// ANTI-PATTERN: Komentar yang menjelaskan "apa" — redundan dengan kode
// Iterasi array dan tambahkan setiap item ke hasil
const hasil = items.map((item) => item.harga * item.kuantitas);

// BENAR: Komentar yang menjelaskan "mengapa" — menambah konteks
// Harga dikalikan kuantitas di sini (bukan di model) agar kalkulasi
// bisa dioverride per transaksi tanpa mengubah data produk
const hasil = items.map((item) => item.harga * item.kuantitas);

// TODO: Tambahkan validasi email format sebelum Sprint 15
// FIXME: Race condition di sini jika dua request masuk bersamaan — lihat issue #892
// HACK: Workaround untuk bug di library axios v1.2.3, hapus setelah upgrade
// NOTE: Fungsi ini dipanggil di 47 tempat — perubahan tanda tangan butuh migration
// PERF: Bisa dioptimasi dengan memoization jika jadi bottleneck di profiling

// ANTI-PATTERN: Komentar yang menduplikasi tipe — akan basi setelah refactoring
/**
 * @param pengguna - Object pengguna dengan properti nama (string) dan usia (number)
 * @returns string
 */
function formatPengguna(pengguna: { nama: string; usia: number }): string {
  return `${pengguna.nama} (${pengguna.usia})`;
}

// BENAR: Komentar fokus pada konteks bisnis, bukan ulang tipe
/**
 * Memformat data pengguna untuk ditampilkan di header profil.
 * Format: "Nama (Usia)" — sesuai desain Figma v3 halaman profil.
 */
function formatPengguna(pengguna: { nama: string; usia: number }): string {
  return `${pengguna.nama} (${pengguna.usia})`;
}

# Install TypeDoc
npm install --save-dev typedoc

# Generate dokumentasi
npx typedoc src/index.ts --out docs/

# Atau konfigurasi via typedoc.json

{
  "entryPoints": ["src/index.ts"],
  "out": "docs",
  "excludePrivate": true,
  "excludeInternal": true,
  "theme": "default"
}