Kode Sumber Komentar Kiat Styling dan Praktik Terbaik

Pengembang yang telah menghabiskan waktu pada proyek-proyek besar memahami pentingnya komentar kode. Ketika Anda membangun banyak fitur ke dalam aplikasi yang sama, banyak hal cenderung menjadi rumit. Ada begitu banyak bit data termasuk fungsi, referensi variabel, nilai balik, parameter ... bagaimana Anda diharapkan untuk mengikuti?

Seharusnya tidak mengejutkan bahwa mengomentari kode Anda sangat penting, baik proyek solo maupun tim. Tetapi banyak pengembang tidak menyadari bagaimana cara melakukan proses ini. Saya telah menguraikan beberapa trik pribadi saya untuk membuat komentar kode yang rapi dan terformat. Template standar dan komentar akan bervariasi di antara pengembang - tetapi pada akhirnya Anda harus berusaha keras komentar bersih dan mudah dibaca untuk lebih jauh menjelaskan area yang membingungkan dalam kode Anda.

Kita harus mulai membahas beberapa perbedaan dalam format komentar. Ini akan memberi Anda ide yang lebih baik tentang seberapa rinci Anda bisa menjadi dengan kode proyek. Setelah itu saya akan menawarkan beberapa tips dan contoh spesifik yang dapat Anda mulai gunakan segera!

Gaya Komentar: Tinjauan

Perlu dicatat bahwa ide-ide yang disajikan ini semata-mata pedoman menuju komentar yang lebih bersih. Bahasa pemrograman individual tidak menetapkan pedoman atau spesifikasi untuk cara mengatur dokumentasi Anda.

Karena itu, pengembang modern telah berkumpul bersama untuk memformat sistem komentar kode mereka sendiri. Saya akan menawarkan beberapa gaya umum dan menjelaskan tujuan mereka.

Mengomentari sebaris

Praktis setiap bahasa pemrograman menawarkan komentar sebaris. Ini terbatas pada konten baris tunggal dan hanya mengomentari teks setelah titik tertentu. Jadi misalnya dalam C / C ++ Anda memulai komentar sebaris seperti ini:

// mulai daftar variabel var myvar = 1; ... 

Ini sangat cocok untuk memasukkan kode ke kode selama beberapa detik menjelaskan fungsionalitas yang mungkin membingungkan. Jika Anda bekerja dengan banyak parameter atau panggilan fungsi, Anda dapat menempatkan banyak komentar inline di dekat Anda. Tetapi penggunaan yang paling bermanfaat adalah a penjelasan sederhana untuk fungsionalitas kecil.

if (callAjax ($ params)) // berhasil menjalankan callAjax dengan parameter pengguna ... kode

Perhatikan di atas semua kode harus berada pada baris baru setelah braket pembuka. Kalau tidak, semua akan tertangkap di baris komentar yang sama! Hindari berlebihan karena Anda biasanya tidak perlu melihat komentar baris tunggal sepanjang halaman Anda, tetapi terutama untuk persimpangan yang membingungkan dalam kode Anda, ini jauh lebih mudah untuk dijatuhkan di menit terakhir.

Blok Deskriptif

Ketika Anda perlu memasukkan penjelasan besar umumnya satu liner tidak akan melakukan trik. Ada templat komentar yang telah diformat sebelumnya yang digunakan di setiap bidang pemrograman. Blok deskriptif paling terlihat di sekitar fungsi dan file perpustakaan. Setiap kali Anda mengatur fungsi baru itu adalah praktik yang baik untuk melakukannya tambahkan blok deskriptif di atas deklarasi.

/ ** * @desc membuka jendela modal untuk menampilkan pesan * @param string $ msg - pesan yang akan ditampilkan * @return bool - sukses atau gagal * / fungsi modalPopup ($ msg) ... 

Di atas adalah contoh sederhana dari komentar fungsi deskriptif. Saya telah menulis suatu fungsi yang mungkin dalam JavaScript disebut modalPopup yang mengambil satu parameter. Dalam komentar di atas saya telah menggunakan sintaksis yang mirip dengan phpDocumentor di mana setiap baris diawali dengan a @ simbol diikuti oleh tombol yang dipilih. Ini tidak akan memengaruhi kode Anda dengan cara apa pun, sehingga Anda bisa menulis @deskripsi dari pada @desc tanpa perubahan apa pun.

Kunci kecil ini sebenarnya disebut tag komentar yang banyak didokumentasikan di situs web. Jangan ragu untuk membuat sendiri dan gunakan ini seperti yang Anda inginkan di seluruh kode Anda. Saya menemukan mereka membantu menjaga semuanya mengalir begitu Sekilas saya dapat memeriksa informasi penting. Anda juga harus memperhatikan bahwa saya telah menggunakan / * * / format komentar gaya blok. Ini akan menjaga semuanya lebih bersih daripada menambahkan garis miring ganda di setiap baris.

Komentar Kelompok / Kelas

Selain mengomentari fungsi dan loop, area blok tidak sering digunakan. Di mana Anda benar-benar membutuhkan yang kuat blokir komentar berada di kepala dokumen backend Anda atau file perpustakaan. Sangat mudah untuk keluar dan menulis dokumentasi yang solid untuk setiap file di situs web Anda - kita dapat melihat praktik ini di banyak CMS seperti WordPress.

Bagian paling atas halaman Anda harus menyimpan komentar mengenai file itu sendiri. Dengan cara ini kamu bisa cepat periksa di mana Anda mengedit saat mengerjakan beberapa halaman secara bersamaan. Selain itu Anda dapat menggunakan area ini sebagai database untuk fungsi paling penting yang Anda perlukan keluar dari kelas.

/ *** kelas abstrak myWebClass  

Anda bisa lihat saya baru saja menggunakan kelas sampel kecil untuk yang palsu myWebClass kode. Saya telah menambahkan beberapa informasi meta dengan nama dan alamat email saya untuk kontak. Ketika pengembang menulis kode sumber terbuka ini umumnya merupakan praktik yang baik sehingga orang lain dapat menghubungi Anda untuk mendapatkan dukungan. Ini juga merupakan metode yang solid ketika bekerja di tim pengembangan yang lebih besar.

Tag @wajib bukan sesuatu yang pernah saya lihat digunakan di tempat lain. Saya mengikuti format di beberapa proyek saya, hanya pada halaman di mana saya telah menyesuaikan banyak metode. Setiap kali Anda memasukkan halaman ke dalam file, mereka harus datang sebelum Anda mengeluarkan kode apa pun. Jadi menambahkan rincian ini ke dalam blok komentar kelas utama adalah cara yang baik untuk melakukannya ingat file mana yang dibutuhkan.

Mengomentari Kode Front-end

Sekarang kita telah membahas 3 templat komentar penting, mari kita lihat beberapa contoh lainnya. Ada banyak pengembang frontend yang telah pindah dari HTML statis ke jQuery dan kode CSS. Komentar HTML tidak memiliki tujuan dibandingkan dengan aplikasi pemrograman, tetapi ketika Anda menulis pustaka gaya dan skrip halaman hal-hal dapat menjadi berantakan dari waktu ke waktu.

JavaScript mengikuti metode komentar yang lebih tradisional yang mirip dengan Java, PHP, dan C / C++. CSS hanya menggunakan komentar gaya blok yang digambarkan dengan garis miring dan tanda bintang. Anda harus ingat bahwa komentar akan ditampilkan secara terbuka kepada pengunjung Anda, karena baik CSS maupun JS tidak di-parsing sisi-server, tetapi salah satu dari metode ini bekerja dengan baik untuk meninggalkan informasi informatif dalam kode Anda untuk kembali.

Khususnya memecah file CSS bisa menjadi tugas. Kita semua akrab dengan meninggalkan komentar sebaris untuk menjelaskan perbaikan untuk Internet Explorer atau Safari. Tapi saya percaya komentar CSS dapat digunakan di level jQuery dan PHP menggunakannya. Mari kita mempelajari cara membuat grup gaya sebelum menyentuh beberapa tips rinci untuk berkomentar kode.

Grup Gaya CSS

Bagi mereka yang telah mendesain CSS selama bertahun-tahun, ini hampir merupakan kebiasaan. Anda perlahan menghafal semua properti, sintaksis, dan membangun sistem Anda sendiri untuk stylesheet. Melalui pekerjaan saya sendiri, saya telah menciptakan apa yang saya sebut pengelompokan untuk memasangkan blok CSS serupa ke dalam satu area.

Ketika kembali mengedit CSS saya dapat dengan mudah menemukan apa yang saya butuhkan dalam beberapa detik. Cara Anda memilih untuk mengelompokkan gaya sepenuhnya tergantung pada Anda, dan itulah keindahan sistem ini. Saya punya beberapa standar yang telah saya uraikan di bawah ini:

• @reset - menghilangkan margin browser default, padding, font, warna, dll.
• @fonts - paragraf, pos, blockquotes, tautan, kode
• @navigation - tautan navigasi situs web inti utama
• @layout - pembungkus, wadah, bilah samping
• @ header & @footer - ini mungkin berbeda berdasarkan desain Anda. Gaya yang mungkin termasuk tautan dan daftar tidak berurutan, kolom footer, heading, sub-navs

Ketika mengelompokkan stylesheet saya telah menemukan sistem penandaan dapat banyak membantu. Namun tidak seperti PHP atau JavaScript saya menggunakan satu @kelompok tag diikuti oleh kategori atau kata kunci. Saya telah menyertakan 2 contoh di bawah ini sehingga Anda dapat merasakan apa yang saya maksud.

/ ** @group footer * / #footer styles…

/ ** @ footer grup, font kecil, kolom, tautan eksternal ** / 

Anda juga dapat menambahkan sedikit detail ekstra di setiap blok komentar. Saya memilih untuk menjaga hal-hal sederhana dan mudah sehingga stylesheet mudah dibaca. Mengomentari adalah semua tentang dokumentasi sehingga selama Anda memahami tulisan itu baik untuk pergi!

4 Tips untuk Styling Gaya Komentar yang Lebih Baik

Kami telah menghabiskan paruh pertama artikel ini untuk melihat berbagai format untuk berkomentar kode. Sekarang mari kita bahas beberapa tips umum untuk menjaga kode Anda tetap bersih, teratur, dan mudah dimengerti.

1. Jagalah agar Semuanya Dapat Dibaca

Terkadang sebagai pengembang kita lupa itu kami menulis komentar untuk dibaca manusia. Semua bahasa pemrograman yang kami pahami dibuat untuk mesin, jadi mungkin membosankan untuk mengubahnya menjadi teks tertulis biasa. Penting untuk dicatat bahwa kita tidak di sini untuk menulis makalah penelitian tingkat perguruan tinggi, tetapi hanya meninggalkan tips!

function getTheMail () // kode di sini akan membuat e-mail / * run code jika fungsi kustom sendMyMail () kita mengembalikan true find sendMyMail () di /libs/mailer.class.php kita periksa apakah pengguna mengisi semua bidang dan pesan terkirim! * / if (sendMyMail ()) return true; // jaga kebenaran dan tampilkan keberhasilan di layar

Bahkan hanya beberapa kata saja lebih baik daripada tidak. Ketika Anda kembali mengedit dan mengerjakan proyek di masa mendatang, sering kali mengejutkan betapa banyak yang akan Anda lupakan. Karena Anda tidak melihat variabel dan nama fungsi yang sama setiap hari, Anda cenderung perlahan-lahan melupakan sebagian besar kode Anda. Jadi kamu bisa jangan pernah meninggalkan terlalu banyak komentar! Tetapi Anda dapat meninggalkan terlalu banyak komentar buruk.

Sebagai aturan umum, luangkan waktu untuk berhenti sejenak dan renungkan sebelum menulis. Bertanya pada diri sendiri apa yang paling membingungkan tentang program ini dan bagaimana Anda bisa menjelaskannya dengan baik “boneka” bahasa? Juga pertimbangkan mengapa Anda menulis kode persis seperti Anda.

Beberapa kesalahan yang paling membingungkan muncul ketika Anda lupa tujuan fungsi yang dibuat khusus (atau pihak ketiga). Tinggalkan jejak komentar yang mengarah kembali ke beberapa file lainnya apakah ini akan membantu Anda mengingat fungsionalitas lebih mudah.

2. Meringankan Beberapa Ruang!

Saya tidak bisa cukup menekankan betapa pentingnya ruang putih dapat. Ini berjalan benar ganda untuk pengembang PHP dan Ruby yang bekerja pada situs web besar dengan ratusan file. Anda akan menatap kode ini sepanjang hari! Bukankah lebih bagus jika Anda bisa membaca bagian-bagian penting saja?

$ dir1 = "/ home /"; // setel direktori home utama $ myCurrentDir = getCurDirr (); // setel direktori pengguna saat ini $ userVar = $ get_username (); // nama pengguna pengguna saat ini

Pada contoh di atas Anda akan melihat padding ekstra yang saya tempatkan di antara komentar dan kode pada setiap baris. Saat Anda menggulir file, gaya komentar ini akan jelas menonjol. Saya t membuat kesalahan menemukan dan memperbaiki kode Anda ratusan kali lebih mudah ketika blok variabel begitu bersih.

Anda dapat melakukan tugas serupa pada kode di dalam fungsi tempat Anda bingung tentang cara kerjanya, tetapi metode ini pada akhirnya akan mengacaukan kode Anda dengan komentar sebaris, dan itu kebalikan yang tepat dari tertib! Saya sarankan dalam skenario ini menambahkan komentar garis-besar di sekitar area logika.

$ (document) .ready (function () $ ('. sub'). hide (); // sembunyikan sub-navigasi pada pageload / ** periksa acara klik pada anchor di dalam .itm div untuk mencegah tautan default tindakan agar halaman tidak berubah saat klik, akses elemen induk .itm diikuti oleh daftar .sub berikutnya untuk beralih buka / tutup ** / $ ('.m a'). live ('klik', fungsi (e ) e.preventDefault (); $ (ini) .parent (). next ('. sub'). slideToggle ('fast');););

Ini adalah sedikit kode jQuery yang menargetkan navigasi geser sub-menu. Komentar pertama adalah inline untuk menjelaskan mengapa kita menyembunyikan semua itu .sub kelas. Di atas pengendali event klik langsung, saya telah menggunakan komentar blok dan indentasi semua tulisan ke titik yang sama. Ini membuat segalanya lebih cantik daripada paragraf yang berjalan - terutama untuk orang lain yang membaca komentar Anda.

3. Komentar Sambil Mengode

Seiring dengan jarak yang tepat ini mungkin menjadi salah satu kebiasaan terbaik untuk masuk. Tidak ada yang ingin kembali ke program mereka setelah bekerja dan mendokumentasikan setiap bagian. Sebagian besar dari kita bahkan tidak ingin kembali dan mendokumentasikan area yang membingungkan! Ini benar-benar membutuhkan banyak pekerjaan.

Tetapi jika Anda dapat menulis komentar saat Anda membuat kode semuanya akan tetap segar di pikiran Anda. Biasanya pengembang akan terjebak pada masalah dan menjelajahi web untuk solusi termudah. Ketika Anda menekan momen Eureka dan menyelesaikan masalah seperti itu pada umumnya ada saat yang jernih di mana Anda memahami kesalahan Anda sebelumnya. Ini akan menjadi waktu terbaik untuk meninggalkan komentar terbuka dan jujur ​​tentang kode Anda.

Selain itu, ini akan memberi Anda latihan membiasakan diri mengomentari semua file Anda. Jumlah waktu yang diperlukan untuk kembali dan mencari tahu bagaimana sesuatu bekerja jauh lebih besar setelah Anda sudah membangun fungsinya. Baik diri masa depan Anda dan rekan satu tim Anda akan berterima kasih karena telah meninggalkan komentar sebelumnya.

4. Menangani Kesalahan Buggy

Kita semua tidak bisa duduk di depan komputer selama berjam-jam menulis kode. Saya kira kita bisa mencoba, tetapi pada titik tertentu kita perlu tidur! Anda mungkin harus berpisah dengan kode Anda untuk hari itu dengan beberapa fitur yang masih rusak. Dalam skenario ini, sangat penting bagi Anda tinggalkan komentar yang panjang dan terperinci tentang di mana Anda tinggalkan.

Bahkan setelah tidur malam yang segar Anda mungkin terkejut dengan betapa sulitnya untuk kembali ke ayunan coding. Misalnya jika Anda sedang membangun halaman unggah gambar dan harus membiarkannya tidak selesai, Anda harus berkomentar tentang di mana dalam proses yang Anda tinggalkan. Apakah gambar diunggah dan disimpan dalam memori temp? Atau mungkin mereka bahkan tidak dikenali dalam formulir unggah, atau mungkin mereka tidak ditampilkan dengan benar di halaman setelah unggah.

Mengomentari kesalahan itu penting karena dua alasan utama. Pertama kamu bisa dengan mudah mengambil tempat Anda tinggalkan dan coba lagi segar dalam pikiran untuk memperbaiki masalah. Dan kedua Anda bisa bedakan antara versi produksi langsung situs web Anda dan alasan pengujian. Ingat bahwa komentar harus digunakan jelaskan mengapa Anda melakukan sesuatu, tidak persis apa yang dilakukannya.

Kesimpulan

Pengembangan aplikasi web dan perangkat lunak adalah praktik yang memuaskan, meskipun sulit. Jika Anda adalah salah satu dari sedikit pengembang yang benar-benar mengerti membangun perangkat lunak maka penting untuk matang dengan keterampilan pengkodean Anda. Meninggalkan komentar deskriptif adalah praktik yang baik dalam jangka panjang, dan Anda mungkin tidak akan pernah menyesalinya!

Jika Anda memiliki saran untuk berkomentar kode yang lebih jelas, beri tahu kami di area diskusi di bawah ini!