Konvensyen anotasi

1. [Mandatori] Ulasan tentang kelas, atribut kelas dan kaedah kelas mesti menggunakan spesifikasi Javadoc dan menggunakan format /**kandungan*/ Kaedah // xxx tidak dibenarkan.

NOTE: di tetingkap penyuntingan IDE, mod Javadoc akan mendorong komen yang relevan, dan Javadoc yang dihasilkan dapat mengeluarkan komen yang sesuai. , parameter, Maksud nilai pulangan meningkatkan kecekapan membaca.

2 [Wajib] Semua kaedah abstrak (termasuk kaedah dalam antara muka) mesti dianotasi dengan Javadoc Selain nilai, parameter dan huraian pengecualian, anda juga mesti menunjukkan kaedah yang dilakukan dan perkara yang dilaksanakan. .

Nota: Sila jelaskan keperluan pelaksanaan untuk subkelas atau langkah berjaga-jaga panggilan.

3 [Wajib] Semua kelas mesti menambah maklumat pencipta.

4. [Mandatori] Komen satu baris di dalam kaedah, mulakan baris baharu di atas pernyataan yang diulas dan gunakan // ulasan. Komen berbilang baris di dalam kaedah

Gunakan /* */ komen, beri perhatian untuk menyelaraskan dengan kod.

5 [Wajib] Semua medan jenis penghitungan mesti mempunyai ulasan untuk menerangkan tujuan setiap item data.

6 [Disyorkan] Daripada mengulas dalam bahasa Inggeris separuh masak, lebih baik menggunakan ulasan Cina untuk menjelaskan masalah dengan jelas. Kata nama dan kata kunci khas boleh kekal dalam teks bahasa Inggeris asal.

Contoh kaunter: "Tamat masa sambungan TCP" ditafsirkan sebagai "Tamat masa sambungan Protokol Kawalan Penghantaran", yang lebih menyusahkan untuk difahami.

7. [Cadangan] Apabila mengubah suai kod, komen juga harus diubah suai dengan sewajarnya, terutamanya pengubahsuaian pada parameter, nilai pulangan, pengecualian, logik teras, dll.

.

Penjelasan: Kemas kini kod dan anotasi tidak segerak, sama seperti kemas kini rangkaian jalan dan perisian navigasi tidak segerak Jika perisian navigasi ketinggalan dengan serius, maksud navigasi akan hilang.

8 [Rujukan] Kod yang diulas hendaklah disertakan dengan arahan sebanyak mungkin, bukannya hanya diulas.

Nota:

Terdapat dua kemungkinan apabila kod dikomen keluar: 1) Logik kod ini akan dipulihkan kemudian. 2) Jangan sesekali menggunakannya. Jika tiada maklumat teguran dalam bekas, sukar untuk mengetahui motivasi anotasi. Yang terakhir disyorkan untuk dipadamkan terus (gudang kod menyimpan kod sejarah).

9. [Rujukan] Keperluan untuk ulasan: Pertama, mereka boleh menggambarkan idea reka bentuk dan logik kod dengan tepat Kedua, mereka boleh menerangkan maksud perniagaan, supaya pengaturcara lain dapat memahami maklumat di sebalik kod tersebut. Sebahagian besar kod tanpa ulasan sama sekali adalah seperti buku syurga kepada pembaca Komen adalah untuk dibaca sendiri, supaya seseorang dapat memahami dengan jelas pemikiran pada masa itu walaupun selepas masa yang lama juga untuk dibaca oleh pengganti. supaya mereka boleh mengambil alih tugas anda dengan pantas. 10 [Rujukan] Penamaan dan struktur kod yang baik adalah jelas dan komen hendaklah ringkas, tepat dan ekspresif. Elakkan satu komen yang melampau: terlalu banyak dan komen yang berlebihan Setelah logik kod diubah suai, mengubah suai komen akan menjadi beban yang besar.

Contoh pembilang:

// put elephant into fridge
put(elephant, fridge);

Nama kaedah yang diletakkan, ditambah dua nama pembolehubah yang bermakna gajah dan peti sejuk, telah menjelaskan perkara yang sedang dilakukan dan kod dengan semantik yang jelas tidak memerlukan ulasan tambahan.

11 [Rujukan] Tanda komen khas, sila nyatakan orang yang menandanya dan masa menandakan. Beri perhatian untuk menangani tanda ini tepat pada masanya, imbas melalui tanda, bersihkan tanda sedemikian dengan kerap. Kesalahan dalam talian kadangkala berpunca daripada kod pada tanda ini.

1) Perkara tugasan (
TODO

): (tanda orang, masa tanda, [anggaran masa pemprosesan])

mewakili fungsi yang perlu dilaksanakan tetapi belum dilaksanakan lagi. Ini sebenarnya adalah teg Javadoc. Javadoc semasa masih belum dilaksanakan, tetapi ia telah digunakan secara meluas. Hanya boleh digunakan pada kelas, antara muka dan kaedah (kerana ia adalah teg Javadoc).

2) Ralat, tidak boleh berfungsi (FIXME): (tanda orang, tanda masa, [anggaran masa pemprosesan])

Gunakan FIXME dalam ulasan untuk menandakan kod tertentu yang salah, tidak boleh berfungsi dan perlu diperbetulkan dalam Keadaan masa.