Comments #

let batasPercobaan: number = 3;        // Limit per security policy
let intervalKadaluarsa: number = 3600; // In seconds — 1 hour

// Start counting from 1, not 0, so error messages feel more natural to users
for (let percobaan = 1; percobaan <= batasPercobaan; percobaan++) {
  console.log(`Percobaan ${percobaan} dari ${batasPercobaan}`);
}

// ANTI-PATTERN: Comments that only repeat the code — no added information
const usia: number = 17; // Set usia to 17
if (usia >= 18) {        // Check whether usia is greater than or equal to 18
  console.log("Dewasa"); // Print "Dewasa"
}

// CORRECT: Comments that explain the reason (the "why"), not the action (the "what")
const usia: number = 17;
if (usia >= 18) {
  // Per Law No. 35 of 2014 — the legal adult age is 18
  console.log("Akses penuh diizinkan");
}

/*
  This algorithm uses a sliding window approach to compute the
  moving average. Time complexity O(n), far more efficient than
  the naive O(n²) approach that recomputes from scratch each iteration.

  Reference: 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());

  /*
  // Additional normalization — temporarily disabled for bug #4521 investigation
  const hasilNormalisasi = hasil.map((item) => {
    return item.replace(/[^a-z0-9]/g, "-");
  });
  return hasilNormalisasi;
  */

  return hasil;
}

/**
 * Calculates the total price after discount and tax are applied.
 *
 * @param harga - Base product price in Rupiah
 * @param diskon - Discount percentage (0–100). Default: 0
 * @param pajakPersen - Tax percentage (0–100). Default: 11 (VAT)
 * @returns Final total price after discount and tax
 *
 * @example
 * ```typescript
 * hitungTotal(100000, 10, 11); // 99900 (10% discount, 11% VAT)
 * hitungTotal(50000);          // 55500 (no discount, 11% VAT)
 * ```
 */
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);
}

/**
 * Product data representation in the e-commerce system.
 * Used for API responses and frontend state.
 */
interface Produk {
  /** Unique product ID — UUID v4 format */
  id: string;

  /** Product name shown to users */
  nama: string;

  /** Price in Rupiah (IDR), not cents */
  harga: number;

  /** Available stock count. 0 means out of stock, -1 means not tracked */
  stok: number;

  /** Product category. Use values from the enum KategoriProduk */
  kategori: string;

  /** Creation timestamp in ISO 8601 format */
  dibuatPada: string;

  /** Main product image URL. Optional — can be null if no image yet */
  gambarUrl?: string | null;
}

/**
 * Service for managing user authentication.
 *
 * @remarks
 * All tokens are stored in memory, not localStorage, to prevent
 * XSS attacks. Tokens are auto-refreshed 5 minutes before expiry.
 *
 * @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;

  /**
   * Creates a new AuthService instance.
   * @param baseUrl - Authentication API base URL (without trailing slash)
   */
  constructor(baseUrl: string) {
    this.baseUrl = baseUrl;
  }

  /**
   * Authenticates the user and stores the token.
   *
   * @param email - User's email address
   * @param password - User's password (sent via HTTPS, never logged)
   * @returns JWT token on success
   * @throws {Error} If credentials are wrong or the server is unreachable
   */
  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"; // An error normally appears, but is ignored

// ANTI-PATTERN: Silent @ts-ignore — no warning if the error is already fixed
// @ts-ignore
fungsiYangSudahDiperbaiki(argumenBenar); // If already correct, @ts-ignore sits "idle" without warning

// CORRECT: @ts-expect-error — the compiler complains if the error doesn't happen
// @ts-expect-error: Deliberately testing with the wrong type to validate runtime error handling
fungsiDenganValidasi("bukan-angka");

// @ts-nocheck
// This file is a migration from JavaScript — type checking is temporarily disabled
// TODO: Remove @ts-nocheck after the migration is complete (target: Sprint 24)

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

// @ts-check
// A plain JavaScript file, but it gets type checking from 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 will report an error

// ANTI-PATTERN: A comment explaining the "what" — redundant with the code
// Iterate the array and add each item to the result
const hasil = items.map((item) => item.harga * item.kuantitas);

// CORRECT: A comment explaining the "why" — adds context
// Price is multiplied by quantity here (not in the model) so the calculation
// can be overridden per transaction without changing product data
const hasil = items.map((item) => item.harga * item.kuantitas);

// TODO: Add email format validation before Sprint 15
// FIXME: Race condition here if two requests arrive simultaneously — see issue #892
// HACK: Workaround for a bug in axios v1.2.3, remove after upgrade
// NOTE: This function is called in 47 places — changing the signature needs a migration
// PERF: Could be optimized with memoization if it becomes a bottleneck in profiling

// ANTI-PATTERN: Comments that duplicate types — will go stale after refactoring
/**
 * @param pengguna - User object with nama (string) and usia (number) properties
 * @returns string
 */
function formatPengguna(pengguna: { nama: string; usia: number }): string {
  return `${pengguna.nama} (${pengguna.usia})`;
}

// CORRECT: Comments focus on business context, not repeating types
/**
 * Formats user data for display in the profile header.
 * Format: "Nama (Usia)" — per Figma v3 design of the profile page.
 */
function formatPengguna(pengguna: { nama: string; usia: number }): string {
  return `${pengguna.nama} (${pengguna.usia})`;
}

# Install TypeDoc
npm install --save-dev typedoc

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

# Or configure via typedoc.json

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