Mencatat alasan, bukan hasilnya

Keputusan tanpa alasan tertulis akan dibatalkan oleh orang berikutnya, dan biasanya orang berikutnya itu Anda sendiri enam bulan kemudian.

Sebaiknya baca lebih dulu: Menulis kebutuhan dari perubahannya.

Dua pelajaran sebelumnya berakhir pada keputusan: di mana batas satu unit kode, dan apa yang sengaja tidak dikerjakan. Keduanya punya sifat yang sama dan itu sifat yang berbahaya. Keduanya tidak terlihat pada hasil akhirnya. Kode yang batasnya dipilih dengan hati hati tampak sama persis dengan kode yang batasnya kebetulan begitu, dan kebutuhan yang batasnya diputuskan tampak sama dengan kebutuhan yang batasnya terlupa.

IngatMenyelesaikan materi tingkat expert tidak menggeser satu pun rating sumbu, dan tidak ada satu pun test yang dapat memeriksa keputusan di tingkat ini. Yang dilatih penilaian, bukan jawaban.

Yang hilang bukan keputusannya, melainkan yang sudah ditolak

Keputusan selalu tersimpan, sebab kodenya sendiri adalah rekamannya. Yang hilang adalah daftar pilihan yang sudah dipertimbangkan lalu ditolak, beserta alasannya. Tanpa daftar itu, orang berikutnya akan mengusulkan kembali pilihan yang sudah ditolak, dan ia berhak melakukannya: dari tempatnya berdiri, pilihan itu memang terlihat lebih baik.

Mencatat hasilnya

Kunci hari memakai UTC.

Mencatat alasan dan yang ditolak

Kunci hari memakai UTC, bukan zona perangkat.

Zona perangkat ditolak: pengguna yang berpindah zona
bisa mendapat dua hari sekaligus atau kehilangan satu
tanpa melakukan kesalahan apa pun.

Konsekuensi yang diterima: batas harinya jatuh pukul
07.00 WIB, bukan tengah malam setempat.

Kolom kiri benar dan tidak berguna. Siapa pun yang menemukannya akan mengira UTC dipilih karena kebiasaan, lalu mengusulkan zona setempat sebagai perbaikan yang ramah pengguna. Kolom kanan menutup usulan itu sebelum diajukan, dan yang menutupnya bukan otoritas melainkan satu kalimat sebab akibat. Bagian konsekuensi juga penting: ia mengumumkan bahwa harga pilihan ini sudah diketahui dan diterima, bukan terlewat.

Tiga baris yang cukup

  • Apa yang dipilih. Satu kalimat, tanpa pembenaran.
  • Apa yang ditolak beserta sebab akibatnya. Ini bagian yang menentukan, dan yang paling sering hilang.
  • Konsekuensi yang diterima. Menyebutkannya membuktikan harganya sudah diketahui, bukan terlewat.

Tiga baris itu sengaja pendek. Catatan keputusan yang menuntut satu halaman tidak akan ditulis, dan catatan yang tidak ditulis tidak lebih baik daripada tidak ada aturannya. Ukuran yang tepat adalah sepanjang yang masih ditulis pada hari yang sibuk.

Tempatnya melekat pada yang diputuskan

Alasan yang disimpan di tempat terpisah akan berpisah dari kodenya, dan itu hanya soal waktu. Yang paling tahan adalah alasan yang tinggal sedekat mungkin dengan keputusannya: di komentar tepat di atas kode yang aneh, di badan permintaan perubahan yang menghasilkannya, atau di dekat butir kebutuhan yang membatasinya. Berkas keputusan tersendiri berguna hanya untuk keputusan yang tidak punya satu tempat, misalnya pilihan yang berlaku di seluruh sistem.

Komentar yang mengulang kodenya

# Menaikkan penghitung sebelum menilai
SET jumlah = jumlah + 1
IF jumlah > batas THEN TOLAK

Komentar yang menjawab kenapa

# Dinaikkan sebelum dinilai, bukan sesudah. Menaikkan
# sesudah membuat dua permintaan bersamaan sama sama
# lolos: keduanya membaca angka lama.
SET jumlah = jumlah + 1
IF jumlah > batas THEN TOLAK

Kolom kiri menuliskan ulang barisnya dalam bahasa Indonesia, jadi ia dapat dihapus tanpa kehilangan apa pun. Kolom kanan memuat satu hal yang tidak ada di kodenya: urutan yang sudah ditolak beserta akibatnya. Perhatikan bahwa urutan pada kolom kanan tampak salah pada pembacaan cepat, dan justru itu alasan komentarnya ada. Yang tidak perlu dijelaskan adalah kode yang sudah terbaca sendiri.

Kapan tidak perlu mencatat

Tidak setiap keputusan layak dicatat, dan mencatat semuanya menghasilkan tumpukan yang tidak akan dibaca siapa pun. Uji yang dapat dipakai: apakah ada pilihan lain yang terlihat wajar bagi pembaca berikutnya? Kalau tidak ada, keputusannya tidak akan diusulkan ulang, jadi tidak ada yang perlu ditutup. Yang layak dicatat hanyalah keputusan yang tampak sewenang wenang dari luar.

Periksa pemahaman

Sebuah tim memilih menyimpan uang sebagai bilangan bulat dalam satuan sen, bukan sebagai bilangan pecahan. Mana catatan yang paling berguna enam bulan kemudian?

  • Kode merekam keputusannya. Yang hilang selalu daftar yang sudah ditolak.
  • Tiga baris: yang dipilih, yang ditolak beserta sebab akibatnya, dan konsekuensi yang diterima.
  • Alasan tinggal sedekat mungkin dengan keputusannya. Yang disimpan terpisah akan berpisah.
  • Komentar yang menuliskan ulang barisnya dapat dihapus. Yang menjawab kenapa tidak dapat digantikan apa pun.
  • Catat hanya keputusan yang tampak sewenang wenang dari luar. Sisanya tidak akan diusulkan ulang.