Merilis, dan Bekerja Sebagai Developer · 7/8

Membaca kode asing dan dokumentasi sungguhan

Keahlian yang bertahan lebih lama dari framework apa pun: menemukan jawaban di codebase yang bukan kamu tulis.

Baca 28 menit

Setelah pelajaran ini kamu bisa

Menemukan jalan di codebase yang bukan kamu tulis
Melacak sebuah fitur dari UI sampai database
Membaca kode sumber library saat dokumentasinya tidak cukup
Menilai apakah dokumentasi yang kamu temukan masih berlaku

Ini keahlian yang bertahan lebih lama dari framework apa pun. Framework berubah setiap beberapa tahun; kemampuan masuk ke codebase yang asing lalu menemukan jawabannya tidak. Ini juga sebagian besar dari apa yang sebenarnya dilakukan developer senior.

Insting kita adalah mulai dari bagian atas sebuah file lalu membaca ke bawah. Itu tidak berhasil di codebase besar, karena tidak ada bagian atasnya. Lacak sebuah fitur sebagai gantinya: pilih sesuatu yang dilakukan pengguna, temukan tempat ia mulai, lalu ikuti.

Coba sendiri

Melacak sebuah fitur dengan mengikuti call graph — penelusuran yang sama seperti "go to definition" di editormu.

// A map of what calls what, taken from this project's real sign-in path.
const calls = {
  "auth-form.tsx: <form action>":        ["actions.ts: signInAction"],
  "actions.ts: signInAction":            ["redirect-target.ts: safeLocale",
                                          "validate.ts: validateCredentials",
                                          "users.ts: authenticate",
                                          "session.ts: createSession",
                                          "redirect-target.ts: safeRedirectTarget"],
  "users.ts: authenticate":              ["db/index.ts: queryOne",
                                          "password.ts: verifyPassword"],
  "password.ts: verifyPassword":         ["node:crypto scrypt", "node:crypto timingSafeEqual"],
  "session.ts: createSession":           ["node:crypto randomBytes",
                                          "session.ts: hashToken",
                                          "db/index.ts: run",
                                          "next/headers: cookies"],
  "db/index.ts: queryOne":               ["node:sqlite prepare/get"],
  "db/index.ts: run":                    ["node:sqlite prepare/run"],
};

function trace(entry, depth = 0, seen = new Set()) {
  const indent = "   ".repeat(depth);
  if (seen.has(entry)) { console.log(indent + entry + "  (already shown)"); return; }
  seen.add(entry);
  console.log(indent + entry);
  for (const callee of calls[entry] ?? []) trace(callee, depth + 1, seen);
}

console.log("what happens when someone signs in:");
console.log("");
trace("auth-form.tsx: <form action>");

console.log("");
// Which leaves are the real boundaries of the system?
const allCallees = Object.values(calls).flat();
const leaves = [...new Set(allCallees)].filter((c) => !calls[c]);
console.log("the edges of this feature - where our code stops:");
for (const leaf of leaves) console.log("   " + leaf);
console.log("");
console.log("Nine of our own functions, and four calls into Node or Next.");
console.log("That is the whole feature, and it fits on one screen.");

Hasil

Tekan Jalankan untuk melihat hasilnya.

Ini jalan di browser kamu, di dalam sandbox. Apa pun yang kamu tulis di sini tidak bisa merusak situs.

Mengenali codebase baru

`README` dan `package.json`. Ini apa, dan perintah apa yang ada? Mulai dari script-nya.
Jalankan. Tidak ada yang lebih cepat mengenalkanmu daripada melihatnya bekerja. Lalu rusak sesuatu dengan sengaja.
Struktur foldernya. Diorganisasi per fitur atau per lapisan? Itu memberitahumu di mana harus mencari sesuatu.
Test-nya. Itu dokumentasi yang bisa dieksekusi tentang apa yang diyakini penulisnya seharusnya dilakukan kodenya.
Satu fitur, dilacak dari ujung ke ujung. Pilih yang paling sederhana dan nyata. Jangan coba memahami semuanya.
Riwayat git pada file yang kamu pedulikan. git log -p <file> menunjukkan kenapa bentuknya seperti itu.

Saat dokumentasinya tidak cukup

Dokumentasi mencakup kasus-kasus umum. Masalahmu sering bukan kasus umum. Saat itu terjadi, jawabannya ada di node_modules — kode sumber sebenarnya dari setiap library yang kamu pakai ada di disk-mu, bisa dibaca.

Baca definisi type-nya dulu. node_modules/<pkg>/**/*.d.ts adalah daftar API yang presisi dan lengkap — sering lebih baik daripada dokumentasinya.
Lalu kode sumbernya. Itu cuma JavaScript. Biasanya tidak sepintar yang kamu takutkan.
Cek versi yang benar-benar kamu punya. cat node_modules/<pkg>/package.json | grep version. Separuh dari semua keluhan "dokumentasinya salah" itu karena membaca dokumentasi untuk versi major yang berbeda.
Baca test di dalam package-nya. Mereka menunjukkan pemakaian yang dimaksudkan, termasuk kasus tepinya.
Lalu issue tracker-nya. Cari issue yang sudah ditutup; biasanya sudah ada yang mengalaminya.

Tugas praktik

Lacak sebuah fitur di proyek ini yang belum kamu baca: mulai dari app/[lang]/dashboard/page.tsx dan ikuti setiap function yang dipanggilnya sampai kamu mencapai database atau sebuah API Next.js. Gambar pohonnya di kertas. Lalu pakai "find all references" pada getSessionUser dan daftar setiap tempat ia dipakai.

Hasil yang diharapkan

Empat atau lima tingkat dalam, berakhir di node:sqlite dan next/headers.