/ ** และ / * ในความคิดเห็น Java

ความแตกต่างระหว่างอะไร

/**
 * comment
 *
 *
 */

และ

/*
 * 
 * comment
 *
 */

ใน Java? ฉันควรใช้เมื่อใด

รูปแบบแรกเรียกว่าJavadoc คุณใช้สิ่งนี้เมื่อคุณเขียน API อย่างเป็นทางการสำหรับรหัสของคุณซึ่งสร้างขึ้นโดยjavadocเครื่องมือ ตัวอย่างเช่นหน้า Java 7 APIใช้ Javadoc และสร้างขึ้นโดยเครื่องมือนั้น

องค์ประกอบทั่วไปบางอย่างที่คุณเห็นใน Javadoc รวมถึง:

• @param: สิ่งนี้ใช้เพื่อระบุว่าพารามิเตอร์ใดที่ถูกส่งผ่านไปยังเมธอดและค่าที่คาดว่าจะมี

• @return: ใช้เพื่อระบุว่าผลลัพธ์จะเป็นอย่างไร

• @throws: ใช้เพื่อระบุว่าวิธีการส่งข้อยกเว้นหรือข้อผิดพลาดในกรณีของการป้อนข้อมูลบางอย่าง

• @since: นี่ใช้เพื่อระบุว่า Java เวอร์ชันเก่าหรือคลาสนี้มีฟังก์ชันใดใน

ตัวอย่างเช่นนี่คือ Javadoc สำหรับcompareวิธีการInteger:

/**
 * Compares two {@code int} values numerically.
 * The value returned is identical to what would be returned by:
 * <pre>
 *    Integer.valueOf(x).compareTo(Integer.valueOf(y))
 * </pre>
 *
 * @param  x the first {@code int} to compare
 * @param  y the second {@code int} to compare
 * @return the value {@code 0} if {@code x == y};
 *         a value less than {@code 0} if {@code x < y}; and
 *         a value greater than {@code 0} if {@code x > y}
 * @since 1.7
 */
public static int compare(int x, int y) {
    return (x < y) ? -1 : ((x == y) ? 0 : 1);
}

รูปแบบที่สองคือความคิดเห็นบล็อก (หลายบรรทัด) คุณใช้สิ่งนี้หากคุณต้องการมีหลายบรรทัดในความคิดเห็น

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

เนื่องจาก Javadoc นั้นมีความหมายมากกว่าทั้งสองและคุณสามารถสร้างเอกสารจริงที่เป็นผลมาจากการใช้มันการใช้ Javadoc จะเป็นที่นิยมมากกว่าในการคอมเม้นท์บล็อกอย่างง่าย

สำหรับ Java ภาษาการเขียนโปรแกรมที่มีความแตกต่างระหว่างคนทั้งสอง Java มีความคิดเห็นสองประเภท: ความคิดเห็นแบบดั้งเดิม ( /* ... */) และความคิดเห็นท้ายบรรทัด ( // ...) ดูข้อมูลจำเพาะภาษา Java ดังนั้นสำหรับภาษาการเขียนโปรแกรม Java ทั้ง/* ... */และ/** ... */เป็นอินสแตนซ์ของความคิดเห็นแบบดั้งเดิมและพวกเขาทั้งสองได้รับการปฏิบัติเหมือนกันโดยคอมไพเลอร์ Java นั่นคือพวกเขาจะถูกละเว้น (หรือมากกว่าอย่างถูกต้อง: พวกเขาจะถือว่าเป็นพื้นที่สีขาว)

อย่างไรก็ตามในฐานะโปรแกรมเมอร์ Java คุณไม่เพียง แต่ใช้คอมไพเลอร์ Java คุณใช้โซ่เครื่องมือทั้งหมดซึ่งรวมถึงเช่นคอมไพเลอร์, IDE, ระบบการสร้าง ฯลฯ และเครื่องมือเหล่านี้บางอย่างตีความสิ่งที่แตกต่างจากคอมไพเลอร์ Java โดยเฉพาะ/** ... */ความคิดเห็นถูกตีความโดยเครื่องมือ Javadoc ซึ่งรวมอยู่ในแพลตฟอร์ม Java และสร้างเอกสาร เครื่องมือ Javadoc จะสแกนไฟล์ต้นฉบับ Java และตีความส่วนต่าง ๆ/** ... */เป็นเอกสาร

สิ่งนี้คล้ายกับแท็กเช่นFIXMEและTODO: หากคุณมีความคิดเห็นเช่น// TODO: fix thisหรือ// FIXME: do thatIDE ส่วนใหญ่จะเน้นความคิดเห็นดังกล่าวเพื่อที่คุณจะไม่ลืมพวกเขา แต่สำหรับ Java พวกเขาเป็นเพียงความคิดเห็น

แรกคือความคิดเห็น Javadoc สามารถประมวลผลได้โดยjavadocเครื่องมือเพื่อสร้างเอกสาร API สำหรับชั้นเรียนของคุณ ประการที่สองคือความคิดเห็นบล็อกปกติ

การอ่านหัวข้อ3.7 ของ JLS เป็นอย่างดีอธิบายสิ่งที่คุณต้องรู้เกี่ยวกับความคิดเห็นใน Java

มีความคิดเห็นสองประเภท:

• / * ข้อความ * /

ความคิดเห็นแบบดั้งเดิม: ข้อความทั้งหมดจากตัวอักษร ASCII / * ถึงตัวอักษร ASCII * / จะถูกละเว้น (เช่นใน C และ C ++)

• // ข้อความ

ความคิดเห็น end-of-line: ข้อความทั้งหมดจากตัวอักษร ASCII // ถึงจุดสิ้นสุดของบรรทัดจะถูกละเว้น (เช่นใน C ++)

เกี่ยวกับคำถามของคุณ

อันแรก

/**
 *
 */

จะใช้ในการประกาศเทคโนโลยี Javadoc

Javadoc เป็นเครื่องมือที่แยกวิเคราะห์การประกาศและความคิดเห็นเอกสารในชุดของไฟล์ต้นฉบับและสร้างชุดของหน้า HTML ที่อธิบายคลาสอินเทอร์เฟซผู้สร้างวิธีการและเขตข้อมูล คุณสามารถใช้ Javadoc doclet เพื่อกำหนด Javadoc เอาต์พุต doclet เป็นโปรแกรมที่เขียนด้วย Doclet API ที่ระบุเนื้อหาและรูปแบบของผลลัพธ์ที่เครื่องมือสร้างขึ้น คุณสามารถเขียน doclet เพื่อสร้างไฟล์ข้อความชนิดใดก็ได้เช่น HTML, SGML, XML, RTF และ MIF Oracle จัดทำเอกสารมาตรฐานสำหรับการสร้างเอกสาร API รูปแบบ HTML Doclets ยังสามารถใช้เพื่อทำงานพิเศษที่ไม่เกี่ยวข้องกับการผลิตเอกสาร API

สำหรับข้อมูลเพิ่มเติมเกี่ยวกับการDocletอ้างถึงAPI

ส่วนที่สองตามที่อธิบายไว้อย่างชัดเจนใน JLS จะไม่สนใจข้อความทั้งหมดระหว่าง/*และ*/ถูกใช้เพื่อสร้างความคิดเห็นหลายบรรทัด

สิ่งอื่น ๆ ที่คุณอาจต้องการทราบเกี่ยวกับความคิดเห็นใน Java

• ความคิดเห็นไม่ซ้อนกัน
• /* and *///ไม่มีความหมายพิเศษในความคิดเห็นที่ขึ้นต้นด้วย
• ///* or /**ไม่มีความหมายพิเศษในความคิดเห็นที่ขึ้นต้นด้วย
• ไวยากรณ์ของคำศัพท์หมายถึงความคิดเห็นที่ไม่เกิดขึ้นภายในตัวอักษรตัวอักษร ( §3.10.4 ) หรือตัวอักษรสตริง ( §3.10.5 )

ดังนั้นข้อความต่อไปนี้เป็นความคิดเห็นที่สมบูรณ์เดียว:

/* this comment /* // /** ends here: */

ฉันไม่คิดว่าคำตอบที่มีอยู่ตอบคำถามนี้ในส่วนที่เพียงพอ:

ฉันควรใช้เมื่อใด

หากคุณกำลังเขียน API ที่จะเผยแพร่หรือนำกลับมาใช้ใหม่ภายในองค์กรของคุณคุณควรเขียนความคิดเห็น Javadoc ที่ครอบคลุมสำหรับทุกpublicคลาสเมธอดและฟิลด์ตลอดจนprotectedวิธีการและฟิลด์ที่ไม่ใช่finalคลาส Javadoc ควรครอบคลุมทุกอย่างที่ไม่สามารถถ่ายทอดโดยลายเซ็นวิธีการเช่นเงื่อนไขเบื้องต้น postconditions อาร์กิวเมนต์ที่ถูกต้องข้อยกเว้นรันไทม์การโทรภายใน ฯลฯ

หากคุณกำลังเขียน API ภายใน (อันที่ใช้โดยส่วนต่าง ๆ ของโปรแกรมเดียวกัน) Javadoc นั้นมีความสำคัญน้อยกว่า แต่เพื่อประโยชน์ของโปรแกรมเมอร์บำรุงรักษาคุณควรเขียน Javadoc สำหรับวิธีการหรือฟิลด์ใด ๆ ที่การใช้หรือความหมายที่ถูกต้องไม่ชัดเจนทันที

"คุณสมบัตินักฆ่า" ของ Javadoc คือมันถูกรวมเข้ากับ Eclipse และ IDE อื่น ๆ อย่างใกล้ชิด ผู้พัฒนาต้องการวางตัวชี้เมาส์เหนือตัวระบุเพื่อเรียนรู้ทุกสิ่งที่พวกเขาจำเป็นต้องรู้ การอ้างถึงเอกสารอย่างต่อเนื่องกลายเป็นเรื่องที่สองสำหรับนักพัฒนา Java ที่มีประสบการณ์ซึ่งจะช่วยปรับปรุงคุณภาพของโค้ดของตนเอง หาก API ของคุณไม่ได้รับการบันทึกด้วย Javadoc นักพัฒนาที่มีประสบการณ์จะไม่ต้องการใช้

ความคิดเห็นในรายการรหัส Java ต่อไปนี้เป็นอักขระสีเทา:

/** 
 * The HelloWorldApp class implements an application that
 * simply displays "Hello World!" to the standard output.
 */
class HelloWorldApp {
    public static void main(String[] args) {
        System.out.println("Hello World!"); //Display the string.
    }
}

ภาษา Java รองรับความคิดเห็นสามประเภท:

/* text */

คอมไพเลอร์ไม่สนใจทุกอย่างจากการ/**/

/** documentation */

สิ่งนี้บ่งชี้ถึงความคิดเห็นเอกสาร (ความคิดเห็น doc สำหรับสั้น) คอมไพเลอร์ไม่สนใจชนิดของความคิดเห็นนี้เช่นเดียวกับที่จะละเว้นความคิดเห็นที่ใช้และ/* */เครื่องมือ JDK javadoc ใช้ความคิดเห็นของ doc เมื่อเตรียมเอกสารที่สร้างขึ้นโดยอัตโนมัติ

// text

คอมไพเลอร์จะไม่สนใจทุกสิ่งตั้งแต่ต้น//จนจบบรรทัด

ตอนนี้เกี่ยวกับเวลาที่คุณควรใช้พวกเขา:

ใช้// textเมื่อคุณต้องการแสดงความคิดเห็นรหัสบรรทัดเดียว

ใช้/* text */เมื่อคุณต้องการแสดงความคิดเห็นโค้ดหลายบรรทัด

ใช้/** documentation */ เมื่อคุณต้องการเพิ่มข้อมูลบางอย่างเกี่ยวกับโปรแกรมที่สามารถใช้สำหรับการสร้างเอกสารของโปรแกรมโดยอัตโนมัติ

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

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

อีกอันคือ // นี่คุณใช้ในระดับคำสั่งเพื่อระบุสิ่งที่บรรทัดการดำเนินการของรหัสควรจะทำ

มีบางอย่างเช่น // สิ่งที่ต้องทำนี่จะทำเครื่องหมายว่าคุณต้องการทำบางสิ่งในภายหลังในสถานที่นั้น

// FIXME คุณสามารถใช้เมื่อคุณมีวิธีแก้ไขปัญหาชั่วคราว แต่คุณต้องการเยี่ยมชมในภายหลังและทำให้ดีขึ้น

หวังว่านี่จะช่วยได้

• ความคิดเห็นเดียวเช่น: // ความคิดเห็น
• ความคิดเห็นหลายบรรทัดเช่น: / * comment * /
• ความคิดเห็น javadoc เช่น: / ** comment * /

Java รองรับความคิดเห็นสองประเภท:

• /* multiline comment */: คอมไพเลอร์ไม่สนใจทุกอย่างจากการ/* */ความคิดเห็นสามารถครอบคลุมหลายบรรทัดได้

• // single line: คอมไพเลอร์จะไม่สนใจทุกสิ่งตั้งแต่ต้น//จนจบบรรทัด

เครื่องมือบางอย่างเช่นjavadocใช้ความคิดเห็นหลายบรรทัดพิเศษสำหรับจุดประสงค์ของพวกเขา ตัวอย่างเช่น/** doc comment */ความคิดเห็นเอกสารที่ใช้โดย javadoc เมื่อเตรียมเอกสารที่สร้างขึ้นโดยอัตโนมัติ แต่สำหรับ Java มันเป็นความคิดเห็นหลายบรรทัดง่าย