Cara menulis komentar saat melakukan

Kata pengantar dari penerjemah

Selama bertahun-tahun pengembangan perangkat lunak, menjadi anggota banyak tim, bekerja dengan berbagai orang yang baik dan berpengalaman, saya sering mengamati (dan sejujurnya, saya menciptakan) masalah yang sama - kekacauan total dalam repositori. Masing-masing menulis komentar tentang commit dengan gayanya sendiri (dan well, jika terus-menerus dalam satu); setengah dari komentar itu tidak berguna (dari kategori " ini jembatan "), setengah dari sisanya tidak dimengerti.

Dan kemudian suatu saat yang baik saya melihat artikel ini, sebelum akhirnya saya mendapatkan terjemahannya. Hanya 7 aturan sederhana dan pendek, dan - lihatlah - melihat sejarah komitmen tidak hanya berguna, tetapi juga menyenangkan. Tidak ada yang revolusioner, semuanya cukup jelas, tetapi dirumuskan dan diringkas dengan baik.

Saya ingin mencatat bahwa ini adalah artikel tahun 2014. Beberapa hal yang sangat tidak relevan yang disebutkan oleh penulis dapat kehilangan relevansinya, tetapi esensi dari artikel tersebut tidak sama sekali.

Pendahuluan: Mengapa Komentar Yang Baik Penting

Jika Anda melihat ke dalam repositori Git acak, kemungkinan besar Anda akan menemukan bahwa ada beberapa jenis kekacauan dalam histori komit. Sebagai contoh, lihatlah mutiara-mutiara ini dari waktu ketika saya mulai melakukan ke repositori Spring:

 $ git log --oneline -5 --autor cbeams --before "Fri 26 Mar 2009"

 e5f4b49 Menambahkan kembali ConfigurationPostProcessorTests setelah penghapusan singkat di r814.  @ Abaikan-ing metode testCglibClassesAreLoadedJustInTimeForEnhancement () karena ternyata ini adalah salah satu penyebab dalam kerusakan build baru-baru ini.  Peretasan classloader menyebabkan efek hilir yang halus, memecahkan tes yang tidak terkait.  Metode pengujian masih berguna, tetapi seharusnya hanya dijalankan secara manual untuk memastikan CGLIB tidak dimuat secara prematur, dan tidak boleh dijalankan sebagai bagian dari pembuatan otomatis.
 2db0f12 memperbaiki dua masalah build-breaking: + mengembalikan ClassMetadataReadingVisitor untuk merevisi 794 + menghapus ConfigurationPostProcessorTests hingga penyelidikan lebih lanjut menentukan mengapa hal itu menyebabkan tes hilir gagal (seperti ClassPathXmlApplicationContextTests yang tampaknya tidak terkait)
 147709f Tweaks ke file package-info.java
 22b25e0 Util Konsolidasi dan kelas MutableAnnotationUtils ke dalam AsmUtils yang ada
 7f96f57 pemolesan

Horor. Bandingkan dengan komitmen terbaru ini di repositori yang sama:

 $ git log --oneline -5 --autw pwebb - sebelum "Sat 30 Agt 2014"

 5ba3db6 Memperbaiki gagal CompositePropertySourceTests
 84564a0 Mengolah logika parsing awal @PropertySource
 e142fd1 Tambahkan tes untuk meta-data ImportSelector
 887815f Perbarui ketergantungan buku catatan dan hasilkan epub
 ac8326d Penggunaan mockito Polandia

Opsi mana yang Anda inginkan?

Yang pertama bervariasi panjang dan gaya, yang terakhir ringkas dan homogen.
Yang pertama diperoleh dengan sendirinya, yang kedua ditulis secara sadar.

Dan meskipun sejarah commit dari banyak repositori sepertinya adalah pilihan pertama, ada beberapa pengecualian. Contoh yang bagus adalah kernel Linux dan Git itu sendiri . Lihatlah Spring Boot atau repositori lainnya yang berhubungan dengan Tim Pope .

Para peserta dalam proyek-proyek ini tahu bahwa komentar yang ditulis dengan baik pada komit adalah cara terbaik untuk memberi tahu konteks perubahan yang dibuat untuk pengembang lain (dan juga untuk diri mereka sendiri di masa depan). Perbedaan dalam revisi menunjukkan apa yang telah berubah, tetapi hanya komentar yang bisa menjelaskan alasannya . Peter Hutterer mengatakannya dengan baik :

Memulihkan dari pengkodean adalah buang-buang waktu. Kami tidak dapat sepenuhnya menghindarinya, jadi upaya kami harus difokuskan pada meminimalkan biaya ini. Itulah komentar untuk komit. Oleh karena itu, mereka menunjukkan apakah programmer bekerja dengan baik dalam tim.

Jika Anda belum benar-benar memikirkan apa yang seharusnya dilakukan oleh komentar komit tingkat pertama, Anda mungkin tidak terlalu sering menggunakan git log dan alat serupa. Ada lingkaran setan: karena sejarah komitmen tidak terstruktur dan heterogen, mereka tidak menggunakannya dan tidak memperhatikan. Dan karena fakta bahwa mereka tidak menggunakannya dan tidak memperhatikan, itu tetap tidak terstruktur dan heterogen.

Tetapi kisah repositori yang dirancang dengan baik adalah hal yang indah dan bermanfaat. Perintah git menyalahkan , mengembalikan , rebase , log , shortlog dan lainnya menjadi hidup . Masuk akal untuk melihat komitmen orang lain dan menarik permintaan, dan, tiba-tiba, sekarang bantuan penulis mereka tidak lagi diperlukan. Untuk memahami mengapa sesuatu terjadi [dalam kode] berbulan-bulan atau bertahun-tahun yang lalu, itu menjadi tidak hanya mungkin, tetapi juga nyaman.

Keberhasilan jangka panjang dari proyek tergantung (antara lain) pada seberapa mudahnya mempertahankan, dan sejarah komitmen adalah salah satu alat paling kuat dari pengelola. Perlu menghabiskan waktu belajar bagaimana menjaga ketertiban di dalamnya. Pada awalnya ini dapat menyebabkan beberapa ketidaknyamanan, tetapi kemudian akan menjadi kebiasaan dan, pada akhirnya, itu akan menjadi sumber kebanggaan dan kerja produktif bagi semua peserta.

Artikel ini hanya menyentuh komponen paling dasar untuk mempertahankan cerita yang bagus, yaitu, bagaimana menulis komentar di komit terpisah. Ada hal-hal penting lainnya, seperti menggabungkan komit yang tidak dibahas di sini.

Kebanyakan bahasa pemrograman memiliki konvensi yang diterima secara umum dengan baik yang membentuk gaya [kode tulisan] yang khas, seperti nama variabel, aturan pemformatan, dan sebagainya. Tentu saja, ada versi berbeda dari perjanjian tersebut, tetapi sebagian besar pengembang berpendapat bahwa memilih satu opsi dan mengikutinya jauh lebih baik daripada berantakan ketika semua orang menulis dengan gayanya sendiri.

Pendekatan tim untuk menggambarkan komitmen harus persis sama. Agar kisah repositori bermanfaat, tim harus mencapai kesepakatan tentang setidaknya tiga poin berikut.

Gaya. Sintaks markup, indentasi, jeda baris, tata bahasa, huruf kapital, tanda baca. Selalu periksa ejaan Anda dan tulis semudah mungkin. Sebagai hasilnya, Anda akan mendapatkan riwayat komit yang sangat lengkap, yang tidak hanya menyenangkan untuk dibaca, tetapi juga akan benar - benar Anda baca secara teratur.

Konten Informasi apa yang harus (jika ada) dimasukkan dalam badan komentar? Mengapa itu tidak ada di sana?

Metadata Bagaimana saya harus merujuk ke ID tugas, menarik nomor permintaan, dll?

Untungnya, sudah ada kesepakatan untuk menulis komentar yang bermakna. Bahkan, mereka sebagian berasal dari cara beberapa perintah Git bekerja. Anda tidak perlu menemukan kembali roda. Cukup ikuti tujuh aturan di bawah ini - dan Anda akan selangkah lebih dekat dengan sejarah komitmen yang layak untuk seorang profesional.

Tujuh aturan untuk komentar komit yang keren

Ingat: Semua ini telah dikatakan sebelumnya .

1. Pisahkan tajuk dari badan dengan string kosong
2. Batasi judul hingga 50 karakter
3. Gunakan huruf besar pada judul
4. Jangan menaruh titik di akhir judul
5. Gunakan imperatif dalam judul.
6. Pergi ke baris berikutnya dalam tubuh dengan 72 karakter
7. Di dalam tubuh, jawab pertanyaan tentang apa dan mengapa , dan bukan bagaimana

Sebagai contoh:

 Ringkas perubahan dalam 50 karakter atau kurang

 Di sini jelaskan secara lebih rinci, jika perlu.  Tindak lanjut
 jeda baris sekitar 72 karakter.  Dalam beberapa situasi
 baris pertama dari komentar dianggap judulnya, dan semuanya 
 sisanya dengan tubuh.  Sangat penting untuk memisahkan untuk memisahkan satu dari yang lain
 string kosong (jika pesan memiliki body sama sekali, tentu saja);
 berbagai alat seperti `log`,` shortlog` dan `rebase` tidak akan mengerti
 Anda jika tajuk dan badan tidak dipisahkan.

 Jelaskan di sini masalah apa yang diselesaikan oleh komit ini.  Bawa pergi 
 lebih banyak perhatian mengapa Anda membuat perubahan ini, bukan untuk 
 persis bagaimana Anda melakukannya (ini akan menjelaskan kode untuk Anda).
 Apakah ada efek samping atau efek tidak jelas lainnya di 
 perubahan ini?  Jika demikian, ini perlu dijelaskan di sini.

 Paragraf dipisahkan oleh garis kosong.

  - Anda dapat melakukan daftar berpoin

  - Biasanya asterisk atau 
    Tanda hubung dengan spasi di depan mereka  tetapi ada perjanjian yang berbeda

 Jika Anda memiliki pelacak bug [atau sistem manajemen proyek],
 letakkan tautan tugas di bagian akhir teks dengan cara ini:

 Dipecahkan: # 123
 Lihat juga: # 456, # 789

1. Pisahkan tajuk dari badan dengan string kosong

Dari manual ke perintah git commit :

Meskipun ini tidak perlu, adalah ide yang baik untuk memulai komentar pada komit dengan satu baris pendek (kurang dari 50 karakter) merangkum perubahan yang dibuat, kemudian baris kosong dan kemudian deskripsi yang lebih rinci. Teks sebelum baris kosong pertama dalam komentar dianggap sebagai header komit dan digunakan dalam berbagai perintah Git. Misalnya, Git-format-patch (1) mengubah komit menjadi email; tim menggunakan tajuk komit untuk subjek surat dan sisa teks untuk badan surat.

Pertama, tidak setiap komit membutuhkan header dan badan. Terkadang satu baris sudah cukup, terutama ketika perubahannya sangat kecil sehingga tidak ada informasi tambahan tentang mereka diperlukan. Sebagai contoh:

  Perbaiki kesalahan ketik pada pengantar panduan pengguna 

Cukup berkata; jika pengguna ingin tahu jenis kesalahan apa yang telah diperbaiki, ia dapat melihat perubahan itu sendiri menggunakan git show atau git diff , atau git log -p .

Jika Anda melakukan sesuatu seperti itu menggunakan baris perintah, akan lebih mudah untuk menggunakan opsi -m untuk git commit :

  $ git commit -m "Perbaiki kesalahan ketik pada pengantar panduan pengguna" 

Namun, ketika komit layak mendapatkan beberapa penjelasan dan deskripsi situasi, Anda perlu menuliskannya di badan komentar. Sebagai contoh:

 Derezz program kontrol utama

 MCP ternyata jahat dan telah menjadi niat dominasi dunia.
 Komit ini melempar cakram Tron ke MCP (menyebabkan keruntuhannya)
 dan mengubahnya kembali menjadi permainan catur.

Komentar yang memiliki isi tidak begitu nyaman untuk ditulis dengan opsi -m . Akan lebih baik menggunakan editor teks untuk ini. Jika Anda belum mengonfigurasi editor untuk digunakan dengan Git, baca bagian buku Pro Git ini .

Dalam hal apa pun, pemisahan judul dan isi komentar akan terbayar saat melihat log. Berikut adalah catatan komit lengkap:

 $ git log
 melakukan 42e769bdf4894310333942ffc5a15151222a87be
 Penulis: Kevin Flynn <kevin@flynnsarcade.com>
 Tanggal: Jum 01 Jan 00:00:00 1982 -0200

  Derezz program kontrol utama

  MCP ternyata jahat dan telah menjadi niat dominasi dunia.
  Komit ini melempar cakram Tron ke MCP (menyebabkan keruntuhannya)
  dan mengubahnya kembali menjadi permainan catur.

Dan inilah perintah git log --oneline , yang hanya menampilkan baris header:

 $ git log --oneline
 42e769 Derezz program kontrol utama

Atau git shortlog, yang dilakukan oleh grup oleh penulis, sekali lagi, untuk singkatnya, hanya menampilkan judul:

 $ git shortlog
 Kevin Flynn (1):
       Derezz program kontrol utama

 Alan Bradley (1):
       Perkenalkan program keamanan "Tron"

 Ed Dillinger (3):
       Ganti nama program catur menjadi "MCP"
       Ubah program catur
       Tingkatkan program catur

 Walter Gibbs (1):
       Memperkenalkan program catur protoype

Ada banyak situasi lain di mana perlu untuk membedakan antara header dan badan dari komit - dan untuk ini mereka harus dipisahkan oleh garis kosong.

2. Batasi judul hingga 50 karakter

Secara teknis, melampaui 50 karakter adalah mungkin, tetapi tidak disarankan. Panjang judul ini menjamin keterbacaannya, dan juga membuat penulis memikirkan kata-kata yang paling singkat dan jelas untuk menggambarkan apa yang terjadi.

Petunjuk: jika sulit bagi Anda untuk merangkum hasil pekerjaan, mungkin satu komit mengandung terlalu banyak perubahan. Berusaha keras untuk membuat komitmen atom (ini adalah topik untuk pos terpisah).

Antarmuka GitHub jelas mendukung konvensi ini. Dia akan memperingatkan Anda jika Anda melampaui batas 50 karakter:


Dan potong semua tajuk lebih dari 72 karakter, gantikan elips:


Jadi bertujuan untuk 50 karakter, tetapi perlu diingat bahwa 72 adalah batasan ketat.

3. Memanfaatkan judul

Semuanya sederhana di sini. Kapitalisasi semua judul.

Sebagai contoh:

• Akselerasi hingga 88 mil per jam

Sebaliknya:

• berakselerasi hingga 88 mil per jam

4. Jangan menaruh titik di akhir judul

Tidak perlu untuk itu. Selain itu, setiap karakter diperhitungkan saat kami mencoba memenuhi 50.

Sebagai contoh:

• Buka pintu ruang pod

Sebaliknya:

• Buka pintu ruang pod.

5. Gunakan imperatif dalam judul.

Imperative mood secara harfiah berarti: suatu bentuk kata kerja yang mengungkapkan wasiat (pesanan, permintaan atau saran). Beberapa contoh:

• Bersihkan kamar Anda (merapikan kamar)
• Tutup pintunya
• Buang sampah

Masing-masing dari tujuh aturan yang Anda baca ditulis dalam mood imperatif ("Pergi ke baris berikutnya dalam tubuh dengan 72 karakter", dll.).

Bentuk ini mungkin terdengar agak kasar, dan karenanya tidak begitu sering digunakan [dalam bahasa Inggris - kira-kira. trans. ] Tapi itu sempurna untuk header komit. Salah satu alasannya adalah fakta bahwa Git menggunakan imperatif ketika itu dilakukan atas nama Anda.
Misalnya, ketika menggunakan git merge, pesan berikut akan ditambahkan secara default:

 Gabungkan cabang 'myfeature'

Dan ketika menggunakan git revert :

 Kembalikan "Tambahkan barang dengan barang-barang"
	
 Ini mengembalikan komit cc87791524aedd593cff5a74532befe7ab69ce9d.

Atau ketika Anda mengklik tombol "Gabung" di antarmuka permintaan tarik di GitHub:

 Gabungkan permintaan penarikan # 123 dari seseorang pengguna / somebranch

Jadi, ketika Anda menulis pesan komit Anda sendiri dalam suasana imperatif, Anda mengikuti aturan yang ditetapkan dalam Git itu sendiri. Sebagai contoh:

• Subsistem refactor X agar mudah dibaca
• Perbarui dokumentasi persiapan
• Hapus metode yang sudah usang
• Versi rilis 1.0.0

Metode ini mungkin awalnya terasa tidak nyaman. Kami lebih terbiasa menggunakan indikatif, yang lebih cenderung melaporkan fakta. Karenanya, komit sering kali berubah menjadi seperti ini:

• Memperbaiki bug dengan Y
• Mengubah perilaku X

Dan kadang-kadang header hanya menggambarkan isi dari komit:

• Lebih banyak perbaikan untuk barang yang rusak
• Metode API baru yang manis

Ada aturan sederhana yang akan memungkinkan Anda untuk menghindari kesalahan.

Header komit yang disusun dengan benar harus menyelesaikan kalimat berikut:

• Jika diterapkan, komit ini akan < komit header >

Sebagai contoh:

• Jika diterapkan, komit ini akan memperbaiki subsistem X agar mudah dibaca
• Jika diterapkan, komit ini akan memperbarui dokumentasi persiapan
• Jika diterapkan, komit ini akan menghapus metode usang
• Jika diterapkan, komit ini akan merilis versi 1.0.0

Jika diterapkan, komit ini akan menggabungkan permintaan tarik # 123 dari pengguna / cabang

Pastikan bahwa kata kerja di mood lain, bukan imperatif, tidak berfungsi di sini:

• Jika diterapkan, komit ini akan memperbaiki bug dengan Y
• Jika diterapkan, komit ini akan mengubah perilaku X
• Jika diterapkan, komit ini akan memperbaiki lebih banyak untuk barang yang rusak
• Jika diterapkan, komit ini akan menjadi metode API baru yang manis

Ingat: menggunakan imperatif hanya penting di header komit. Di tubuh komit, ini opsional.

6. Pergi ke baris berikutnya dalam tubuh dengan 72 karakter

Git sendiri tidak mengatur jeda baris secara otomatis. Saat mengedit badan komentar, Anda harus mengingat batas kanan dan mengatur jeda baris secara manual.

Dianjurkan agar Anda pergi ke baris berikutnya dengan 72 karakter sehingga Git dapat indentasi dan masih sesuai dengan 80 karakter secara total.

Editor teks yang baik dapat membantu dengan ini. Sangat mudah untuk mengonfigurasi, katakan, Vim, untuk memberi makan 72 karakter untuk menulis pesan ke komit. Namun, kebetulan bahwa IDE sangat buruk dalam mendukung jeda baris pintar untuk melakukan pesan (meskipun versi terbaru dari IntelliJ IDEA akhirnya menjadi lebih baik di bagian ini). ( sekitar per. - mungkin saat ini semuanya jauh lebih baik ).

7. Di dalam tubuh, jawab pertanyaan "apa" dan "mengapa", bukan "bagaimana"

Komit dari repositori Bitcoin ini memberikan penjelasan yang sangat baik tentang apa dan mengapa telah berubah:

 komit eb0b56b19017ab5c16c745e6da39c53126924ed6
 Penulis: Pieter Wuille <pieter.wuille@gmail.com>
 Tanggal: Jum 1 Agustus 22:57:55 2014 +0200

    Sederhanakan penanganan pengecualian serialize.h

    Hapus 'state' dan 'exceptionmask' dari aliran serialize.h
    implementasi, serta metode terkait.

    Seperti exceptionmask selalu menyertakan 'failbit', dan setstate selalu
    dipanggil dengan bits = failbit, yang dilakukannya hanyalah menaikkan
    pengecualian.  Singkirkan variabel-variabel itu, dan ganti setstate
    dengan melemparkan pengecualian langsung (yang juga menghilangkan beberapa mati
    kode).

    Akibatnya, kebaikan () tidak pernah tercapai setelah kegagalan (ada
    hanya 2 panggilan, salah satunya dalam tes), dan hanya bisa diganti
    oleh! eof ().

    fail (), clear (n) dan exception () tidak pernah dipanggil.  Hapus
    mereka.

Lihatlah perubahan dalam kode dan pikirkan tentang berapa banyak waktu yang dihemat penulis untuk peserta proyek saat ini dan di masa depan, yang menggambarkan konteks pekerjaan yang dilakukan dalam komentar. Kalau tidak, dia mungkin akan hilang selamanya.

Dalam kebanyakan kasus, Anda dapat menghilangkan detail tentang bagaimana perubahan dilakukan. Biasanya, kode berbicara untuk dirinya sendiri dalam hal ini (dan jika sangat rumit sehingga diperlukan klarifikasi, maka ada komentar untuk itu di dalamnya).

Fokus terutama pada menjelaskan mengapa perubahan dilakukan - gambarkan situasi sebelum perubahan dilakukan (dan apa yang terjadi), situasi setelahnya, dan mengapa Anda memilih cara khusus untuk menyelesaikan masalah ini.

Mungkin di masa depan Anda akan berterima kasih pada diri sendiri untuk ini!

Kiat

Suka baris perintah. Lupa tentang IDE.

Ada banyak alasan - dengan jumlah perintah Git - untuk menggunakan baris perintah secara maksimal. Git adalah alat yang sangat kuat; IDE - juga, tetapi masing-masing dengan caranya sendiri. Saya menggunakan IntelliJ IDEA setiap hari, saya sering harus berurusan dengan orang lain (misalnya, Eclipse), tetapi saya tidak pernah melihat bahwa integrasi Git dalam IDE dapat dibandingkan dalam kesederhanaan dan kemampuan ke baris perintah (segera setelah Anda memahaminya).

Fitur tertentu dari IDE untuk kontrol versi sangat berharga, misalnya, secara otomatis mengeksekusi git rm ketika Anda menghapus file, atau potongan git lain yang diperlukan ketika Anda mengganti nama file tersebut. Tetapi itu jauh lebih buruk ketika Anda mencoba untuk melakukan, menggabungkan, rebase, atau melakukan analisis kompleks dari sejarah komitmen menggunakan IDE.

Ketika Anda perlu membuka kunci potensi penuh Git, baris perintah tidak ada duanya.
Ingat bahwa apakah Anda menggunakan Bash, Zsh atau Powershell - ada skrip untuk menyelesaikan perintah yang menyelamatkan Anda dari kebutuhan yang menyakitkan untuk mengingat semua sub-perintah dan opsi.

Baca Buku Pro Git

Buku Pro Git yang luar biasa ( juga dalam bahasa Rusia - terjemahan. ) Tersedia secara bebas. Manfaatkan ini!