ความคิดเห็น

ดังที่เราทราบจากบทที่ โครงสร้างโค้ด ความคิดเห็นอาจเป็นบรรทัดเดียว: เริ่มต้นด้วย // และหลายบรรทัด: /* ... */

โดยปกติแล้วเราจะใช้เพื่ออธิบายวิธีการและสาเหตุที่โค้ดทำงาน

ตั้งแต่แรกเห็น ความคิดเห็นอาจจะชัดเจน แต่มือใหม่ในการเขียนโปรแกรมมักใช้ผิด

ความคิดเห็นที่ไม่ดี

มือใหม่มักจะใช้ความคิดเห็นเพื่ออธิบาย "เกิดอะไรขึ้นในโค้ด" แบบนี้:

 // โค้ดนี้จะทำสิ่งนี้ (...) และสิ่งนั้น (...)
// ...และใครจะรู้อะไรอีกบ้าง...
มาก;
ซับซ้อน;
รหัส;

แต่ในโค้ดที่ดี จำนวนความคิดเห็นที่ "อธิบาย" ควรมีน้อย จริงๆ แล้วโค้ดควรจะเข้าใจได้ง่ายหากไม่มีพวกมัน

มีกฎสำคัญเกี่ยวกับเรื่องนั้น: “หากโค้ดไม่ชัดเจนจนต้องมีความคิดเห็น ก็ควรเขียนโค้ดใหม่แทน”

สูตรอาหาร: แยกฟังก์ชันออก

บางครั้งการแทนที่โค้ดด้วยฟังก์ชันก็มีประโยชน์ อย่างเช่นที่นี่:

 ฟังก์ชั่น showPrimes (n) {
  ต่อไปนายกรัฐมนตรี:
  สำหรับ (ให้ i = 2; i < n; i++) {

    // ตรวจสอบว่า i เป็นจำนวนเฉพาะหรือไม่
    สำหรับ (ให้ j = 2; j < i; j++) {
      ถ้า (i % j == 0) ดำเนินการต่อถัดไปนายกรัฐมนตรี;
    -

    การแจ้งเตือน (ฉัน);
  -
-

ตัวแปรที่ดีกว่าพร้อมฟังก์ชันแยกตัวประกอบ isPrime :

 ฟังก์ชั่น showPrimes (n) {

  สำหรับ (ให้ i = 2; i < n; i++) {
    ถ้า (!isPrime(i)) ดำเนินการต่อ;

    การแจ้งเตือน (ฉัน);
  -
-

ฟังก์ชั่น isPrime (n) {
  สำหรับ (ให้ i = 2; i < n; i++) {
    ถ้า (n % i == 0) คืนค่าเท็จ;
  -

  กลับเป็นจริง;
-

ตอนนี้เราสามารถเข้าใจโค้ดได้อย่างง่ายดาย ฟังก์ชั่นนั้นจะกลายเป็นความคิดเห็น รหัสดังกล่าวเรียกว่า self-descriptive

สูตรอาหาร: สร้างฟังก์ชัน

และถ้าเรามี “แผ่นโค้ด” ยาวๆ แบบนี้:

 // นี่เราเติมวิสกี้
สำหรับ (ให้ i = 0; i <10; i++) {
  ให้ปล่อย = getWhiskey();
  กลิ่น(หยด);
  เพิ่ม(หยด, แก้ว);
-

// นี่เราเติมน้ำผลไม้
สำหรับ(ให้ t = 0; t < 3; t++) {
  ให้มะเขือเทศ = getTomato();
  ตรวจสอบ(มะเขือเทศ);
  ให้น้ำผลไม้ = กด(มะเขือเทศ);
  เพิ่ม(น้ำผลไม้, แก้ว);
-

-

ถ้าอย่างนั้น อาจเป็นตัวแปรที่ดีกว่าหากปรับโครงสร้างใหม่ให้เป็นฟังก์ชันต่างๆ เช่น:

 เพิ่มวิสกี้(แก้ว);
เพิ่มน้ำผลไม้(แก้ว);

ฟังก์ชั่น addWhiskey (คอนเทนเนอร์) {
  สำหรับ (ให้ i = 0; i < 10; i ++) {
    ให้ปล่อย = getWhiskey();
    -
  -
-

ฟังก์ชั่น addJuice (คอนเทนเนอร์) {
  สำหรับ(ให้ t = 0; t < 3; t++) {
    ให้มะเขือเทศ = getTomato();
    -
  -
-

อีกครั้งที่ตัวทำหน้าที่บอกสิ่งที่เกิดขึ้น ไม่มีอะไรจะแสดงความคิดเห็น และโครงสร้างโค้ดจะดีกว่าเมื่อแยก มันชัดเจนว่าทุกฟังก์ชั่นทำอะไร ต้องใช้อะไร และส่งคืนอะไร

ในความเป็นจริง เราไม่สามารถหลีกเลี่ยงความคิดเห็นที่ "อธิบาย" ได้โดยสิ้นเชิง มีอัลกอริธึมที่ซับซ้อน และมี "การปรับแต่ง" อันชาญฉลาดเพื่อวัตถุประสงค์ในการเพิ่มประสิทธิภาพ แต่โดยทั่วไปเราควรพยายามทำให้โค้ดเรียบง่ายและสื่อความหมายได้ในตัว

ความคิดเห็นที่ดี

ดังนั้น ความคิดเห็นที่อธิบายมักจะไม่ดี ความเห็นไหนดี?

• อธิบายสถาปัตยกรรม

• ให้ภาพรวมระดับสูงของส่วนประกอบ วิธีโต้ตอบของส่วนประกอบต่างๆ ขั้นตอนการควบคุมในสถานการณ์ต่างๆ คืออะไร... สรุปสั้นๆ ก็คือ มุมมองจากมุมสูงของโค้ด มีภาษาพิเศษ UML เพื่อสร้างไดอะแกรมสถาปัตยกรรมระดับสูงเพื่ออธิบายโค้ด น่าศึกษาอย่างแน่นอน

• พารามิเตอร์ฟังก์ชันเอกสารและการใช้งาน

• มีไวยากรณ์พิเศษ JSDoc เพื่อบันทึกฟังก์ชัน: การใช้งาน พารามิเตอร์ ค่าที่ส่งคืน

ตัวอย่างเช่น:

 -
 * ส่งค่า x ยกกำลัง n
 -
 * @param {number} x จำนวนที่จะเพิ่ม
 * @param {number} n กำลัง ต้องเป็นจำนวนธรรมชาติ
 * @return {number} x ยกกำลัง n
 -
ฟังก์ชั่นธาร(x, n) {
  -
-

ความคิดเห็นดังกล่าวช่วยให้เราเข้าใจวัตถุประสงค์ของฟังก์ชันและใช้อย่างถูกต้องโดยไม่ต้องดูโค้ด

อย่างไรก็ตาม ผู้แก้ไขจำนวนมากเช่น WebStorm ก็สามารถเข้าใจสิ่งเหล่านี้ได้เช่นกัน และใช้สิ่งเหล่านี้เพื่อเติมข้อความอัตโนมัติและการตรวจสอบโค้ดอัตโนมัติ

นอกจากนี้ยังมีเครื่องมือเช่น JSDoc 3 ที่สามารถสร้างเอกสาร HTML จากความคิดเห็นได้ คุณสามารถอ่านข้อมูลเพิ่มเติมเกี่ยวกับ JSDoc ได้ที่ https://jsdoc.app

• เหตุใดงานจึงแก้ไขด้วยวิธีนี้

• สิ่งที่เขียนเป็นสิ่งสำคัญ แต่สิ่งที่ ไม่ได้ เขียนไว้อาจสำคัญกว่าในการทำความเข้าใจสิ่งที่เกิดขึ้น เหตุใดงานจึงได้รับการแก้ไขด้วยวิธีนี้ รหัสไม่ได้ให้คำตอบ

  หากมีหลายวิธีในการแก้ปัญหาทำไมถึงทำเช่นนี้? โดยเฉพาะอย่างยิ่งเมื่อมันไม่ชัดเจนที่สุด

  หากไม่มีความคิดเห็นดังกล่าว สถานการณ์ต่อไปนี้ก็เป็นไปได้:

  1. คุณ (หรือเพื่อนร่วมงานของคุณ) เปิดโค้ดที่เขียนไว้เมื่อนานมาแล้ว และเห็นว่าโค้ดนั้น "ไม่ดีนัก"

  2. คุณคิดว่า: "ตอนนั้นฉันโง่แค่ไหนและตอนนี้ฉันฉลาดขึ้นแค่ไหน" และเขียนใหม่โดยใช้รูปแบบที่ "ชัดเจนและถูกต้องมากขึ้น"

  3. …แรงกระตุ้นให้เขียนใหม่เป็นสิ่งที่ดี แต่ในกระบวนการนี้ คุณจะเห็นว่าแท้จริงแล้วยังขาดวิธีแก้ปัญหาที่ "ชัดเจนยิ่งขึ้น" คุณจำได้ไม่ชัดเจนว่าทำไม เพราะคุณลองมันมานานแล้ว คุณเปลี่ยนกลับเป็นรูปแบบที่ถูกต้อง แต่เสียเวลาไป

  ความคิดเห็นที่อธิบายวิธีแก้ปัญหามีความสำคัญมาก ช่วยพัฒนาต่อไปอย่างถูกวิธี

• มีคุณลักษณะที่ละเอียดอ่อนของโค้ดหรือไม่? พวกเขาใช้ที่ไหน?

• หากโค้ดมีอะไรที่ละเอียดอ่อนและขัดกับสัญชาตญาณ ก็คุ้มค่าที่จะแสดงความคิดเห็นอย่างแน่นอน

สรุป

สัญญาณสำคัญของนักพัฒนาที่ดีคือความคิดเห็น: การมีอยู่และแม้กระทั่งการขาดหายไป

ความคิดเห็นที่ดีช่วยให้เรารักษาโค้ดได้ดี กลับมาใช้อีกครั้งหลังจากล่าช้าและใช้งานได้อย่างมีประสิทธิภาพมากขึ้น

ความคิดเห็นนี้:

• สถาปัตยกรรมโดยรวม วิวระดับสูง

• การใช้ฟังก์ชั่น

• แนวทางแก้ไขที่สำคัญโดยเฉพาะเมื่อไม่ชัดเจนในทันที

หลีกเลี่ยงความคิดเห็น:

• นั่นบอกว่า "โค้ดทำงานอย่างไร" และ "มันทำอะไร"

• ใส่เข้าไปเฉพาะในกรณีที่เป็นไปไม่ได้ที่จะทำให้โค้ดเรียบง่ายและสื่อความหมายได้เองจนไม่จำเป็นต้องใช้

ความคิดเห็นยังใช้สำหรับเครื่องมือจัดทำเอกสารอัตโนมัติเช่น JSDoc3 โดยจะอ่านและสร้างเอกสาร HTML (หรือเอกสารในรูปแบบอื่น)