Source Code Comment Styling Tips dan Amalan Terbaik

Pemaju yang telah menghabiskan masa pada projek besar memahami kepentingan komen kod. Apabila anda membina banyak ciri ke dalam aplikasi yang sama, perkara cenderung menjadi rumit. Terdapat banyak bit data termasuk fungsi, rujukan pemboleh ubah, nilai pulangan, parameter ... bagaimana anda dijangka akan terus maju?

Ia harus mengejutkan bahawa mengulas kod anda adalah penting, kedua-dua projek solo dan pasukan. Tetapi ramai pemaju tidak menyedari tentang bagaimana proses ini dijalankan. Saya telah menggariskan beberapa helah peribadi saya untuk membuat komen kod yang rumit dan rumit. Piawai dan templat komen akan berbeza antara pemaju - tetapi akhirnya anda harus berusaha ke arah komen yang bersih dan boleh dibaca untuk terus menerangkan kawasan yang mengelirukan dalam kod anda.

Kita harus mula membincangkan beberapa perbezaan dalam pemformatan komen. Ini akan memberi anda gambaran yang lebih baik tentang bagaimana terperinci anda boleh menjadi dengan kod projek. Selepas itu, saya akan menawarkan beberapa petua dan contoh khusus yang boleh anda gunakan dengan segera!

Gaya Ulasan: Tinjauan Keseluruhan

Harus diingat bahawa idea-idea yang dikemukakan hanyalah semata-mata garis panduan ke arah komen yang bersih. Bahasa pengaturcaraan individu tidak menetapkan garis panduan atau spesifikasi untuk membuat persediaan dokumentasi anda.

Bahwa dikatakan, pemaju moden telah dikumpulkan bersama untuk memformat sistem mereka sendiri mengulas kod. Saya akan menawarkan beberapa gaya arus perdana dan terperinci mengenai tujuan mereka.

Mengulas Inline

Secara praktikal setiap tawaran bahasa pengaturcaraan tunggal ulasan sebaris. Ini adalah terhad kepada kandungan baris tunggal dan hanya memberi komen teks selepas titik tertentu. Oleh itu, contohnya dalam C / C ++ anda memulakan komen sebaris seperti ini:

// memulakan penyenaraian pembolehubah var myvar = 1; ... 

Ini adalah sempurna untuk melengkapkan kod untuk beberapa saat terangkan fungsi yang mungkin mengelirukan. Sekiranya anda bekerja dengan banyak parameter atau panggilan berfungsi, anda boleh meletakkan ulasan sebaris yang berdekatan. Tetapi penggunaan yang paling bermanfaat adalah a penjelasan ringkas untuk fungsi kecil.

jika (callAjax ($ params)) // berjaya menjalankan callAjax dengan parameter pengguna ... code

Notis di atas semua kod itu perlu berada di barisan baru selepas pendakap pembukaan. Sekiranya tidak semuanya akan ditangkap pada baris komen yang sama! Elakkan pergi ke laut kerana anda secara amnya tidak perlu melihat komen satu talian sepanjang jalan ke halaman anda, tetapi terutamanya untuk persimpangan yang mengelirukan dalam kod anda, ini lebih mudah untuk dilepaskan pada minit terakhir.

Blok Deskriptif

Apabila anda perlu memasukkan penjelasan yang besar pada umumnya, satu pelantar tidak akan melakukan silap mata. Terdapat templat komen pra-format yang digunakan dalam setiap bidang pengaturcaraan. Blok deskriptif yang paling ketara dilihat di sekeliling fungsi dan fail perpustakaan. Setiap kali anda membuat persediaan fungsi baru, amalan yang baik tambah blok deskriptif di atas perisytiharan.

/ ** * @desc membuka tetingkap modal untuk memaparkan mesej * @param string $ msg - mesej yang akan dipaparkan * @return bool - kejayaan atau kegagalan * / fungsi modalPopup ($ msg) ... 

Di atas adalah contoh mudah bagi komen fungsi deskriptif. Saya telah menulis satu fungsi yang mungkin disebut JavaScript modalPopup yang mengambil satu parameter. Dalam ulasan di atas saya telah menggunakan sintaks yang serupa dengan phpDocumentor di mana setiap baris didahului dengan a @ simbol diikuti oleh kunci yang dipilih. Ini tidak akan mempengaruhi kod anda dengan cara apapun, jadi anda boleh menulis @description bukannya @desc tanpa sebarang perubahan.

Kekunci kecil ini sebenarnya dipanggil teg komen yang banyak didokumenkan di laman web. Jangan ragu untuk membuat sendiri dan gunakan ini seperti yang anda inginkan sepanjang kod anda. Saya mendapati mereka membantu untuk memastikan semuanya mengalir begitu Saya boleh menyemak maklumat penting sepintas lalu. Anda juga harus melihat saya telah menggunakannya / * * / format mengulas gaya blok. Ini akan menyimpan segala-galanya lebih bersih daripada menambah permulaan slash berganda pada setiap baris.

Komen Kumpulan / Kelas

Selain mengulas fungsi dan gelung, kawasan blok tidak digunakan dengan kerap. Di mana anda benar-benar memerlukan kuat blok ulasan berada di kepala dokumen backend atau fail perpustakaan anda. Sangat mudah untuk pergi keluar dan menulis dokumentasi pepejal untuk setiap fail di laman web anda - kita dapat melihat amalan ini di banyak CMS seperti WordPress.

Kawasan paling atas halaman anda harus memegang komen mengenai fail itu sendiri. Dengan cara ini anda boleh cepat semak di mana anda sedang mengedit apabila bekerja pada berbilang halaman pada masa yang sama. Di samping itu, anda boleh menggunakan kawasan ini sebagai pangkalan data untuk fungsi yang paling penting yang anda perlukan keluar dari kelas.

/ ** * @desc kelas ini akan memegang fungsi untuk interaksi pengguna * contoh termasuk user_pass (), user_username (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * @required settings.php * / kelas abstrak myWebClass  

Anda dapat melihat saya hanya menggunakan kelas sampel kecil untuk palsu myWebClass kod. Saya telah menambah beberapa maklumat meta dengan nama dan alamat e-mel saya untuk dihubungi. Apabila pemaju menulis kod sumber terbuka, amalan ini biasanya amalan yang baik supaya orang lain boleh menghubungi anda untuk sokongan. Ini juga merupakan kaedah pepejal apabila bekerja di pasukan pembangunan yang lebih besar.

Tag itu @ perlukan bukan sesuatu yang saya lihat digunakan di tempat lain. Saya telah mengikuti format dalam beberapa projek saya, hanya pada muka surat yang saya telah menyesuaikan banyak kaedah. Apabila anda memasukkan halaman ke dalam fail, mereka mesti datang sebelum anda mengeluarkan sebarang kod. Jadi menambah butiran ini ke dalam blok komen utama kelas adalah cara yang baik untuk ingat fail yang diperlukan.

Mengulas Kod Penyambut

Sekarang kita telah meliputi 3 templat komen penting, mari kita lihat beberapa contoh lain. Terdapat banyak pemaju frontend yang telah berpindah dari HTML statik ke jQuery dan kod CSS. Komen HTML tidak semestinya berbanding dengan aplikasi pengaturcaraan, tetapi apabila anda menulis perpustakaan gaya dan halaman skrip perkara dapat berkeliaran dari masa ke masa.

JavaScript mengikuti kaedah yang lebih tradisional mengulas sama seperti Java, PHP, dan C / C++. CSS hanya menggunakan komen gaya blok yang ditandakan dengan slash dan asterisk. Anda harus ingat bahawa komen akan dipaparkan secara terbuka kepada pelawat anda, kerana CSS atau JS tidak diparalelkan di sisi pelayan, tetapi salah satu daripada kaedah ini berfungsi dengan baik untuk meninggalkan notifikasi maklumat dalam kod anda untuk kembali.

Khususnya memecah fail CSS boleh menjadi tugas. Kita semua kenal dengan meninggalkan komen sebaris untuk menjelaskan suatu penetapan untuk Internet Explorer atau Safari. Tetapi saya percaya CSS mengulas boleh digunakan pada tahap jQuery dan PHP menggunakannya. Mari kita hubungkan ke dalam membuat kumpulan gaya sebelum menyentuh beberapa tip terperinci untuk mengulas kod.

Kumpulan Gaya CSS

Bagi mereka yang telah merancang CSS selama bertahun-tahun ia hampir menjadi sifat kedua. Anda perlahan-lahan menghafal semua sifat, sintaks, dan membina sistem anda sendiri untuk stylesheet. Melalui kerja saya sendiri, saya telah membuat apa yang saya panggil kumpulan untuk memasangkan blok CSS yang serupa ke satu kawasan.

Apabila kembali mengedit CSS, saya dapat dengan mudah mencari apa yang saya perlukan dalam beberapa saat. Cara anda memilih untuk gaya kumpulan sepenuhnya terpulang kepada anda, dan itulah keindahan sistem ini. Saya mempunyai beberapa piawaian pratetap yang saya telah tertera di bawah:

• @reset - mengambil margin pelayar lalai, padding, fon, warna, dan sebagainya.
• @fonts - perenggan, tajuk, sekatan, pautan, kod
• @navigasi - pautan navigasi laman utama teras laman web
• @layout - wrapper, container, sidebars
• @header & @ footer - ini mungkin berbeza mengikut reka bentuk anda. Gaya yang mungkin termasuk pautan dan senarai tanpa had, lajur kaki, tajuk, sub-nav

Apabila stylesheets pengelompokan saya dapati sistem penandaan boleh membantu banyak. Namun tidak seperti PHP atau JavaScript saya menggunakan satu @kumpulan tag yang diikuti oleh kategori atau kata kunci. Saya telah memasukkan 2 contoh di bawah supaya anda dapat merasakan apa yang saya maksudkan.

/ ** @group footer * / #footer styles ...

/ ** @ footer kumpulan, fon kecil, lajur, pautan luaran ** / 

Anda boleh menambah sedikit detail tambahan dalam setiap blok komen. Saya pilih menjaga perkara-perkara yang mudah dan mudah jadi stylesheets mudah dipetik. Mengulas semua mengenai dokumentasi selagi anda memahami tulisan itu bagus untuk pergi!

4 Tips untuk Mengomentari Komen Baik

Kami telah menghabiskan separuh pertama artikel ini melihat pelbagai format untuk mengulas kod. Mari kita membincangkan beberapa petua untuk memastikan kod anda bersih, teratur, dan mudah difahami.

1. Simpan Segalanya Boleh Dibaca

Kadang-kadang sebagai pemaju kita lupa bahawa kami menulis komen untuk manusia untuk dibaca. Semua bahasa pengaturcaraan yang kita fahami dibina untuk mesin, jadi ia boleh membosankan untuk ditukar menjadi teks bertulis biasa. Adalah penting untuk diperhatikan bahawa kita tidak berada di sini untuk menulis kertas penyelidikan peringkat kolej, tetapi hanya meninggalkan tip!

fungsi getTheMail () // kod di sini akan membina e-mel / * kod lari jika fungsi sendMyMail () fungsi kami kembali pulih mencari sebenar sendMyMail () di /libs/mailer.class.php kita periksa jika pengguna mengisi dalam semua bidang dan mesej dihantar! * / if (sendMyMail ()) return true; // teruskan dan paparkan kejayaan pada skrin

Malah hanya beberapa perkataan sahaja lebih baik daripada apa-apa. Apabila anda kembali mengedit dan mengusahakan projek di masa depan, ia sering mengejutkan betapa anda akan lupa. Oleh kerana anda tidak melihat pembolehubah yang sama dan nama fungsi setiap hari, anda cenderung perlahan melupakan majoriti kod anda. Oleh itu, anda boleh tidak pernah meninggalkan terlalu banyak komen! Tetapi anda boleh meninggalkan komen yang terlalu banyak.

Sebagai peraturan umum, mengambil sedikit masa untuk menjeda dan merenung sebelum menulis. Tanya diri anda apa yang paling membingungkan mengenai program ini dan bagaimana anda boleh menerangkannya dengan baik “dummy” bahasa? Juga pertimbangkan mengapa anda menulis kod dengan tepat seperti anda.

Antara kesilapan yang paling membingungkan muncul apabila anda terlupa tujuan fungsi (atau pihak ke-3) yang tersuai. Tinggalkan jejak komen yang membawa kepada beberapa fail lain jika ini akan membantu anda mengingati fungsi lebih mudah.

2. Mengurangkan Beberapa Ruang!

Saya tidak boleh menekankan betapa pentingnya ruang kosong boleh jadi. Ini berlaku duanya sekali lagi untuk pemaju PHP dan Ruby yang bekerja di laman web besar-besaran dengan beratus-ratus fail. Anda akan menatap kod ini sepanjang hari! Bukankah lebih baik jika anda hanya dapat melangkah ke kawasan-kawasan penting?

$ dir1 = "/ home /"; / / set direktori utama rumah $ myCurrentDir = getCurDirr (); // tetapkan direktori pengguna semasa $ userVar = $ get_username (); / // Nama pengguna pengguna semasa

Dalam contoh di atas, anda akan melihat padding ekstra yang saya buat antara komen dan kod pada setiap baris. Seperti yang anda sedang menatal melalui fail, gaya komen ini akan jelas menonjol. Ia membuat kesilapan mencari dan membetulkan kod anda ratusan kali lebih mudah apabila blok berubah begitu bersih.

Anda boleh melakukan tugas yang sama pada kod di dalam suatu fungsi di mana anda keliru tentang cara ia berfungsi, tetapi kaedah ini pada akhirnya akan melumpuhkan kod anda dengan ulasan sebaris, dan itu bertentangan dengan tepat! Saya mencadangkan dalam senario ini menambah komentar barisan besar di sekitar kawasan logik.

$ (document) .ready (function () $ ('. sub'). hide (); // hide sub-navigation on pageload / ** check for event click on anchor inside. tindakan supaya halaman tidak berubah pada klik klik elemen induk dari .itm diikuti oleh senarai .sub seterusnya untuk toggle buka / tutup ** / $ ('.membuat a'). hidup ('klik', fungsi (e ) e.preventDefault (); $ (this) .parent (). next ('. sub'). slideToggle ('fast');););

Ini adalah sedikit jQuery yang menyasarkan navigasi sub-menu navigasi. Kenyataan pertama adalah selaras untuk menjelaskan mengapa kita bersembunyi .sub kelas. Di atas pengendali acara klik langsung saya telah menggunakan ulasan blok dan mengaitkan semua tulisan ke titik yang sama. Ini menjadikan perkara-perkara yang lebih cantik dan bukannya peralihan - terutamanya bagi orang lain yang membaca komen anda.

3. Komen Semasa Pengkodan

Bersama dengan jarak yang sepatutnya ini mungkin salah satu tabiat terbaik untuk masuk. Tiada siapa yang mahu kembali ke program mereka selepas ia berfungsi dan dokumen setiap bahagian. Kebanyakan kita tidak mahu kembali dan mendokumenkan kawasan yang mengelirukan! Ia benar-benar mengambil banyak kerja.

Tetapi jika anda boleh menulis komen semasa anda sedang mengkode semuanya masih segar dalam fikiran anda. Biasanya pemaju akan terjebak masalah dan menjejaki web untuk penyelesaian yang paling mudah. Apabila anda memukul momen Eureka dan menyelesaikan masalah sedemikian biasanya terdapat momen kejelasan di mana anda memahami kesilapan anda sebelum ini. Ini akan menjadi masa terbaik untuk meninggalkan komen terbuka dan jujur ​​tentang kod anda.

Di samping itu, ini akan memberi anda amalan untuk membiasakan semua fail anda. Jumlah masa yang diperlukan untuk kembali dan mengetahui bagaimana sesuatu berfungsi lebih besar selepas anda telah membina fungsi tersebut. Kedua-dua masa depan diri dan rakan sepasukan anda akan berterima kasih kepada anda untuk meninggalkan ulasan terlebih dahulu.

4. Menangani Kesalahan Buggy

Kita tidak boleh duduk di hadapan komputer untuk menulis kod berjam-jam. Saya rasa kita boleh cuba, tetapi pada satu ketika kita perlu tidur! Anda mungkin perlu memisahkan cara dengan kod anda untuk hari ini dengan beberapa ciri masih rosak. Dalam senario ini adalah penting bahawa anda tinggal lama, komen terperinci tentang tempat anda meninggalkan perkara.

Walaupun selepas tidur malam yang segar anda mungkin terkejut dengan betapa sukarnya untuk kembali ke ayunan pengekodan. Sebagai contoh, jika anda membina laman muat naik imej dan perlu membiarkannya tidak selesai, anda harus memberi komen mengenai di mana dalam proses yang anda tinggalkan. Adakah imej dimuat naik dan disimpan dalam memori temp? Atau mungkin mereka tidak diiktiraf dalam borang muat naik, atau mungkin mereka tidak dipaparkan dengan betul pada halaman selepas memuat naik.

Mengulas ralat adalah penting untuk dua sebab utama. Pertama anda boleh mudah mengambil tempat yang anda tinggalkan dan cuba lagi segar di minda untuk menyelesaikan masalah (s). Dan kedua, anda boleh membezakan antara versi pengeluaran langsung laman web anda dan alasan ujian. Ingat bahawa komen harus digunakan untuk terangkan mengapa anda melakukan sesuatu, tidak betul-betul apa yang dilakukannya.

Kesimpulannya

Pembangunan untuk aplikasi web dan perisian adalah amalan yang memuaskan, walaupun sukar. Jika anda adalah salah satu dari beberapa pemaju yang benar-benar memahami perisian bangunan maka penting untuk matang dengan kemahiran pengekodan anda. Meninggalkan komen deskriptif hanya praktik yang baik dalam jangka masa panjang, dan anda mungkin tidak akan menyesalinya!

Sekiranya anda mempunyai cadangan untuk mengulas kod yang lebih jelas, beritahu kami di kawasan perbincangan di bawah!