Latihan - Membuat komentar kode yang efektif

13 menit

Dalam latihan ini, Anda akan menambahkan catatan ke kode Anda dan menonaktifkan baris kode tertentu untuk sementara waktu dari kompilasi. Kemudian Anda akan melihat bagaimana pengkompilasi C# memahami spasi kosong dan cara menggunakan spasi kosong untuk meningkatkan keterbacaan kode Anda.

Apa itu komentar kode?

Komentar kode adalah instruksi kepada pengompilasi untuk mengabaikan semuanya setelah simbol komentar kode di baris saat ini.

// This is a code comment!

Ini mungkin tampak tidak berguna pada awalnya, namun berguna dalam tiga situasi:

Saat Anda ingin meninggalkan catatan tentang niat dari suatu bagian kode. Sangat membantu untuk menyertakan komentar kode yang menjelaskan tujuan atau proses pemikiran ketika Anda menulis serangkaian instruksi pengkodean yang sangat menantang. Diri masa depan Anda akan berterima kasih.
Saat Anda ingin menghapus kode sementara dari aplikasi Anda untuk mencoba pendekatan lain, tetapi Anda belum yakin ide baru Anda akan berhasil. Anda dapat mengomentari kode, menulis kode baru, dan setelah Anda yakin kode baru akan berfungsi seperti yang Anda inginkan, Anda dapat menghapus kode lama (kode komentar) dengan aman.
Menambahkan pesan seperti TODO untuk mengingatkan Anda agar melihat bagian kode yang diberikan nanti. Meskipun Anda harus menggunakan ini secara yudisius, itu adalah pendekatan yang berguna. Anda mungkin sedang mengerjakan fitur lain saat membaca sebaris kode yang memicu kekhawatiran. Daripada mengabaikan masalah baru, Anda dapat menandainya untuk diselidiki nanti.

Catatan

Komentar kode harus digunakan untuk mengatakan apa yang tidak dapat dilakukan kode. Seringkali, pengembang memperbarui kode mereka tetapi lupa memperbarui komentar kode. Yang terbaik adalah menggunakan komentar untuk ide tingkat yang lebih tinggi dan tidak menambahkan komentar tentang cara kerja setiap baris kode.

Menyiapkan lingkungan pengodian Anda

Modul ini mencakup latihan yang memandu Anda melalui proses membangun dan menjalankan kode sampel. Anda didorong untuk menyelesaikan aktivitas ini menggunakan Visual Studio Code sebagai lingkungan pengembangan Anda. Menggunakan Visual Studio Code untuk aktivitas ini akan membantu Anda menjadi lebih nyaman menulis dan menjalankan kode di lingkungan pengembang yang digunakan oleh para profesional di seluruh dunia.

Buka Visual Studio Code.

Anda dapat menggunakan Windows menu Mulai (atau sumber daya yang setara untuk OS lain) untuk membuka Visual Studio Code.
Pada menu File Visual Studio Code, pilih Buka Folder.
Dalam dialog Buka Folder , navigasikan ke folder Windows Desktop.

Jika Anda memiliki lokasi folder yang berbeda di mana Anda menyimpan proyek kode, Anda dapat menggunakan lokasi folder tersebut sebagai gantinya. Untuk pelatihan ini, yang penting adalah memiliki lokasi yang mudah ditemukan dan diingat.
Dalam dialog Buka Folder , pilih Pilih Folder.

Jika Anda melihat dialog keamanan yang menanyakan apakah Anda mempercayai penulis, pilih Ya.
Pada menu Terminal Visual Studio Code, pilih Terminal Baru.

Perhatikan bahwa perintah di panel Terminal menampilkan jalur folder untuk folder saat ini. Contoh:
```
C:\Users\someuser\Desktop>
```
Catatan

Jika Anda bekerja pada PC Anda sendiri daripada di kotak pasir atau lingkungan yang dihosting dan Anda telah menyelesaikan modul Microsoft Learn lainnya dalam seri C# ini, Anda mungkin telah membuat folder proyek untuk sampel kode. Jika demikian, Anda dapat melewati langkah berikutnya, yang digunakan untuk membuat aplikasi konsol di folder TestProject.
Pada prompt perintah Terminal, untuk membuat aplikasi konsol baru di folder tertentu, masukkan perintah berikut:
```
dotnet new console -o ./CsharpProjects/TestProject
```
Perintah .NET CLI ini menggunakan templat program .NET untuk membuat proyek aplikasi konsol C# baru di lokasi folder yang ditentukan. Perintah membuat folder CsharpProjects dan TestProject untuk Anda, dan menggunakan TestProject sebagai nama file Anda .csproj .

Jika pesan ditampilkan memberi tahu Anda bahwa file sudah ada, lanjutkan dengan langkah berikutnya. Anda akan menggunakan kembali file proyek yang ada.
Dalam tampilan EXPLORER, perluas folder CsharpProjects .

Anda akan melihat folder TestProject dan dua file, file program C# bernama Program.cs dan file proyek C# bernama TestProject.csproj.
Pada menu File Visual Studio Code, pilih Buka Folder.
Dalam dialog Buka Folder , pilih folder CsharpProjects , lalu pilih Pilih Folder.
Dalam tampilan EXPLORER, perluas folder TestProject, lalu pilih Program.cs.
Hapus baris kode yang ada.

Anda akan menggunakan proyek konsol C# ini untuk membuat, membangun, dan menjalankan sampel kode selama modul ini.
Tutup panel Terminal.

Membuat dan menggunakan komentar kode

Dalam tugas ini, Anda akan membuat dan menghapus berbagai jenis komentar kode.

Di panel Editor Visual Studio Code, masukkan kode berikut:

string firstName = "Bob";
int widgetsSold = 7;
Console.WriteLine($"{firstName} sold {widgetsSold} widgets.");

Untuk mengubah kode Anda dengan komentar dan revisi kode, perbarui kode Anda sebagai berikut:

string firstName = "Bob";
int widgetsPurchased = 7;
// Testing a change to the message.
// int widgetsSold = 7;
// Console.WriteLine($"{firstName} sold {widgetsSold} widgets.");
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");

Luangkan waktu semenit untuk meninjau komentar dan pembaruan kode Anda.

Perhatikan bahwa komentar kode digunakan untuk mendokumentasikan potensi perubahan yang dilakukan, dan untuk menonaktifkan pesan lama untuk sementara saat Anda menguji pesan baru. Langkah Selanjutnya adalah menguji pembaruan Anda. Jika Anda puas dengan kode baru, Anda dapat dengan aman menghapus kode lama yang dikomentari. Ini adalah pendekatan yang lebih aman dan lebih metodis untuk memodifikasi kode kerja sampai Anda yakin bahwa Anda siap untuk menghapusnya secara permanen.
Pada menu File Visual Studio Code, klik Simpan.
Dalam tampilan EXPLORER, untuk membuka Terminal di lokasi folder TestProject Anda, klik kanan TestProject, lalu pilih Buka di Terminal Terintegrasi.
Pada prompt perintah Terminal, ketik dotnet run lalu tekan Enter.

Anda akan menemukan output berikut:
```
Bob purchased 7 widgets.
```
Sekali lagi, jika Anda puas dengan pembaruan Anda, hapus kode lama yang dikomentari.

Hapus komentar kode.

Kode Anda harus cocok dengan yang berikut:

string firstName = "Bob";
int widgetsPurchased = 7;
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");

Untuk menerapkan komentar blok yang mengomentari beberapa baris, perbarui kode Anda sebagai berikut:
```
/*
string firstName = "Bob";
int widgetsPurchased = 7;
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");
*/
```
Komentar blokir sangat bagus jika Anda perlu menulis komentar panjang atau menghapus banyak baris kode. Blokir komentar menggunakan /* di awal kode dan */ di akhir. Menggunakan komentar blok adalah cara tercepat dan term mudah untuk menonaktifkan tiga baris kode atau lebih.

Ganti kode yang sudah ada dengan yang berikut ini:

Random random = new Random();
string[] orderIDs = new string[5];
// Loop through each blank orderID
for (int i = 0; i < orderIDs.Length; i++)
{
    // Get a random value that equates to ASCII letters A through E
    int prefixValue = random.Next(65, 70);
    // Convert the random value into a char, then a string
    string prefix = Convert.ToChar(prefixValue).ToString();
    // Create a random number, pad with zeroes
    string suffix = random.Next(1, 1000).ToString("000");
    // Combine the prefix and suffix together, then assign to current OrderID
    orderIDs[i] = prefix + suffix;
}
// Print out each orderID
foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

Catatan

Ada banyak konsep C# dalam daftar kode ini yang mungkin baru bagi Anda. Tidak perlu memahami apa yang dilakukan kode untuk menghargai bagaimana komentar dapat membantu pembaca memahami tujuan kode.

Luangkan waktu semenit untuk melihat apakah Anda dapat mencari tahu tujuan kode.

Mengingat komentar, Anda mungkin dapat mengetahui apa yang dilakukan kode (dengan asumsi komentar secara akurat menggambarkan keadaan saat ini dan diperbarui saat kode diperbarui). Tapi bisakah Anda menebak mengapa kode ini ada? Tidakkah akan berguna jika ada beberapa penjelasan di bagian atas file kode yang memberikan beberapa konteks dan menjelaskan tujuannya?
Pertimbangkan bagaimana Anda akan meningkatkan komentar.

Perhatikan bahwa ada dua masalah utama dengan komentar ini:
- Komentar kode tidak perlu menjelaskan fungsionalitas yang jelas dari masing-masing baris kode. Ini dianggap komentar berkualitas rendah karena hanya menjelaskan cara kerja C# atau metode .NET Class Library. Jika pembaca tidak terbiasa dengan ide-ide ini, mereka dapat mencarinya menggunakan learn.microsoft.com atau IntelliSense.
- Komentar kode tidak memberikan konteks apa pun untuk masalah yang dipecahkan oleh kode. Ini dianggap komentar berkualitas rendah karena pembaca tidak mendapatkan wawasan apa pun tentang tujuan kode ini, terutama yang berkaitan dengan sistem yang lebih besar.

Hapus komentar yang ada.

Kode Anda harus cocok dengan yang berikut:

Random random = new Random();
string[] orderIDs = new string[5];

for (int i = 0; i < orderIDs.Length; i++)
{
    int prefixValue = random.Next(65, 70);
    string prefix = Convert.ToChar(prefixValue).ToString();
    string suffix = random.Next(1, 1000).ToString("000");

    orderIDs[i] = prefix + suffix;
}

foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

Perhatikan bahwa kode sudah kurang berantakan.

Untuk menambahkan komentar yang menjelaskan tujuan tingkat yang lebih tinggi dari kode Anda, perbarui kode Anda sebagai berikut:

/*
  The following code creates five random OrderIDs
  to test the fraud detection process.  OrderIDs 
  consist of a letter from A to E, and a three
  digit number. Ex. A123.
*/
Random random = new Random();
string[] orderIDs = new string[5];

for (int i = 0; i < orderIDs.Length; i++)
{
    int prefixValue = random.Next(65, 70);
    string prefix = Convert.ToChar(prefixValue).ToString();
    string suffix = random.Next(1, 1000).ToString("000");

    orderIDs[i] = prefix + suffix;
}

foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

Kegunaan komentar bersifat subjektif. Dalam semua hal yang berkaitan dengan keterbacaan kode, Anda harus menggunakan penilaian terbaik Anda. Lakukan apa yang menurut Anda terbaik untuk meningkatkan kejelasan kode Anda.

Rekap

Poin utama dari latihan ini:

Gunakan komentar kode untuk meninggalkan catatan yang bermakna kepada diri Anda sendiri tentang masalah yang dipecahkan kode Anda.
Jangan gunakan komentar kode yang menjelaskan cara kerja C# atau .NET Class Library.
Gunakan komentar kode saat mencoba solusi alternatif untuk sementara hingga Anda siap untuk berkomitmen pada solusi kode baru, di mana Anda dapat menghapus kode lama.
Jangan pernah percaya komentar. Komentar mungkin tidak mencerminkan status kode saat ini setelah banyak perubahan dan pembaruan.

Saran dan Komentar

Apakah halaman ini membantu?