ความคิดเห็นใน Java: ไม่ใช่ทุกอย่างจะง่ายนัก

การแนะนำ

ความคิดเห็น - ดูเหมือนว่าจะง่ายกว่านี้และทำไมต้องเขียนบทความทั้งหมด แต่มันไม่ง่ายขนาดนั้น อย่างที่เจ้านายของฉันบอก ใครๆ ก็เขียนโค้ดได้ แต่การเขียนความคิดเห็นที่ดีนั้นยาก หลักสูตรภาษาส่วนใหญ่เริ่มต้นด้วย Hello World แบบดั้งเดิม แม้แต่ในOracle Tutorialsในส่วน "การเริ่มต้น" เราก็เริ่มต้นด้วย"Hello World!" แอปพลิเคชัน . และจากบรรทัดแรกของโค้ดที่เราเห็น - ความคิดเห็น Java ความสำคัญของพวกเขายังถูกเน้นย้ำด้วยข้อเท็จจริงที่ว่าในเอกสารสำคัญเช่น Java Code Convention ความคิดเห็นจะได้รับส่วนแยกต่างหาก: ความคิดเห็น ตามเอกสารประกอบ ความคิดเห็นใน Java แบ่งออกเป็นสองประเภท:

• ความคิดเห็นในการใช้งาน (หรือความคิดเห็นเกี่ยวกับโค้ด);
• บันทึกความคิดเห็น

ความคิดเห็นเกี่ยวกับโค้ดใช้เพื่ออธิบายแต่ละบรรทัด/บล็อก และความคิดเห็นเกี่ยวกับเอกสารใช้เพื่ออธิบายข้อกำหนดของโค้ด (อินเทอร์เฟซ) โดยไม่ขึ้นอยู่กับการใช้งาน ความคิดเห็น Java จะถูกละเว้นโดยคอมไพเลอร์เพราะว่า มันสมเหตุสมผลสำหรับนักพัฒนา ไม่ใช่ผู้ใช้ ดังนั้นคุณสามารถลดขนาดของคลาสที่คอมไพล์ได้

ความคิดเห็นเกี่ยวกับโค้ด Java

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

• ตัวพิมพ์เล็ก (เช่น อธิบายไว้ในบรรทัดเดียว)

  // Строчный комментарий
  System.out.println("Hello, World!");




• บล็อก (กล่าวคือ อธิบายเป็นบล็อกทั้งหมด เนื่องจากไม่พอดีกับบรรทัดเดียว)

  /*
   * Блочный комментарий
   */
  System.out.println("Hello");

คุณลักษณะที่น่าสนใจของความคิดเห็นแบบบล็อกก็คือ ถ้าเราขึ้นต้นด้วย " /*- " (เช่น เพิ่มเครื่องหมายลบหลังเครื่องหมายดอกจัน) ข้อความของความคิดเห็นแบบบล็อกนี้จะไม่ถูกจัดรูปแบบ น่าสนใจ แต่ด้วยความช่วยเหลือของความคิดเห็นบางอย่าง คุณสามารถให้คำแนะนำ IDE บางอย่างได้ ตัวอย่างเช่น การใช้ความคิดเห็นแบบอินไลน์ " //@formatter:on " และ " //@formatter:off " ใน Eclipse IDE คุณสามารถปิดใช้งานการจัดรูปแบบสำหรับส่วนของโค้ดได้ คุณต้องใช้ความคิดเห็นเท่าที่จำเป็นและเท่าที่จำเป็นเท่านั้น ตัวอย่างเช่น คุณสามารถอ่านบทความในหัวข้อนี้: “อย่าเขียนความคิดเห็นเกี่ยวกับโค้ด!” . มีหนังสือดีๆ ชื่อClean Code: การสร้าง การวิเคราะห์ และการปรับโครงสร้างใหม่โดย Robert Martin มีบท "ความคิดเห็น" แยกต่างหาก เพื่อเป็นบทสรุปของบทนี้ มีคำพูดที่ยอดเยี่ยมไม่แพ้กัน: “Don't comment bad code—rewrite it” จาก Brian W. Kernighan และ P. J. Plower บท นี้สามารถพบได้ในGoogle หนังสือ ความหมายทั่วไปสามารถแสดงออกมาได้ในคำพูดเดียวจากเขา:

ทุกครั้งที่แสดงความคิดเห็น สะดุ้งและรู้สึกเหมือนล้มเหลว”

เป็นที่ชัดเจนว่าไม่มีความจริงที่แน่นอน และบางครั้งก็จำเป็นต้องมีความคิดเห็น แต่ก็มีทางเลือกอยู่เสมอ และจำเป็นต้องต่อสู้กับความคิดเห็นที่ไม่จำเป็น บทนี้ยังกล่าวถึงความคิดเห็นที่ผิดปกติ สิ่งที่ต้องทำ:

// TODO: Добавить World
System.out.println("Hello, ");

ประเด็นก็คือสามารถจัดการได้ด้วยวิธีพิเศษใน IDE ตัวอย่างเช่น ใน IDEA ข้อมูลเหล่านี้จะถูกรวบรวมไว้ในแท็บแยกต่างหาก ซึ่งคุณสามารถดูได้: และปริศนาเล็กๆ ที่มีความคิดเห็น: บรรทัด “http://google.com” เป็นบรรทัดที่ถูกต้องภายในวิธีการ เนื่องจาก http นี่คือแท็กจริงๆ แล้วตามด้วยความคิดเห็น บ่อยครั้งที่ความคิดเห็นจำนวนมากสามารถไปจากความคิดเห็นเกี่ยวกับโค้ดไปจนถึงความคิดเห็นเกี่ยวกับเอกสาร ซึ่งเราจะพูดถึงในภายหลัง

ความคิดเห็นสำหรับเอกสาร

ความคิดเห็นในเอกสารอธิบาย API สาธารณะ APIคืออินเทอร์เฟซการเขียนโปรแกรมแอปพลิเคชัน ซึ่งก็คือคลาสและเมธอดที่นักพัฒนารายอื่นสามารถใช้เพื่อดำเนินการใดๆ ได้ โดยสรุป ความคิดเห็นเหล่านี้ควรอธิบายว่าทำไมสิ่งนี้หรือคลาสและแพ็คเกจจึงถูกสร้างขึ้น และสิ่งนี้หรือเมธอดนั้นทำอะไร คุณยังสามารถอธิบายฟิลด์ของชั้นเรียนได้หากจำเป็น นี่คือสิ่งที่เราเห็นในคำแนะนำเครื่องมือของ IDE ของเรา ซึ่งแสดงเป็น JavaDoc ตัวอย่างเช่น: หากเราพิจารณาวิธีนี้ เราจะเห็นว่าข้อความนี้มาจากไหน: โปรดดู Java Code Convention อีกครั้ง: Code Convention เกี่ยวกับวิธีการจัดรูปแบบ JavaDoc อย่าง เหมาะสม ค่อนข้างคล้ายกับความคิดเห็นแบบบล็อก แต่แทนที่จะใช้เครื่องหมายดอกจันหนึ่งอัน (ไม่ใช่ Asterix)) จะใช้สองอัน ตัวอย่าง JavaDoc ได้รับข้างต้น ไม่มีประโยชน์ที่จะอธิบายความเป็นไปได้ทั้งหมด เนื่องจากมีการเขียนไว้แล้วในเอกสารอย่างเป็นทางการของ Oracle ดังนั้นเราจึงดูทุกสิ่งที่คุณต้องการใน เอกสารประกอบ JavaDoc อย่างเป็นทางการ ในส่วน "คำอธิบายแท็ก" Oracle ยังมีบทช่วยสอนแยกต่างหากในหัวข้อนี้: วิธีเขียนความคิดเห็น Doc สำหรับเครื่องมือ Javadoc คำแนะนำเครื่องมือใน IDE นั้นดี แต่จริงๆ แล้วมันเป็นเอกสารด้วยเหตุผล ตามข้อคิดเห็น JavaDoc เหล่านี้ เอกสารจะถูกสร้างขึ้น มียูทิลิตี้ javadoc พิเศษ สำหรับสิ่งนี้ ดังที่เราเห็นแล้วว่า Tutorial พูดถึงเรื่องนี้ คำอธิบายวิธีใช้งานมีอยู่บนเว็บไซต์อย่างเป็นทางการของ Oracle สำหรับJavaDoc หากต้องการดูว่าสิ่งนี้เป็นอย่างไร คุณสามารถสร้างไดเร็กทอรีย่อยในไดเร็กทอรีด้วยชื่อแพ็กเกจ เช่น: test สร้างชั้นเรียนแบบง่ายๆ พร้อมความคิดเห็นในนั้น ตัวอย่างเช่น:

package test;

/**
 * This is a JavaDoc class comment
 */
public class JavaDocTest {

  /**
   * This is a JavaDoc public field comment
   */
  public static final String HELLO_MESSAGE = "Hello, World!";

  public static void main(String... args) {
    JavaDocTest.greetings();
  }

  /**
   * This is a JavaDoc public method comment
   */
  public static void greetings() {
    System.out.println(HELLO_MESSAGE);
  }
}

หลังจากนี้ เราสามารถรันคำสั่งต่อไปนี้จากไดเร็กทอรีที่มีไดเร็กทอรีแพ็คเกจของเรา: javadoc -d ./test test หลังจากนี้ เราจะเห็นกระบวนการสร้างเอกสาร จากนั้นเราสามารถเปิด index.html เพื่อดูเอกสารที่สร้างขึ้นได้ คุณมักจะเห็นการโพสต์เอกสาร API ตัวอย่างเช่นSpring Framework API

บทสรุป

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