เอกสารประกอบพร้อมคอมเมนต์
แนะนำใหม่| English | ความหมาย |
|---|---|
| comment/ˈkɒment/ | คอมเมนต์ |
Comment does not repair an active formula
- สำหรับราคา 100,
total = price * 10 / 100;จะคำนวณผลลัพธ์เป็น 10 แม้ว่าจะมี comment (_heading) ระบุว่า "จำนวนเงินหลังหักส่วนลด 10%" แล้ว การแก้ไขคำอธิบายนั้นจะไม่ทำให้นิพจน์คำนวณได้ผลเป็น 90 - เปลี่ยน active expression เป็น
price * 90 / 100เพื่อคำนวณจำนวนเงินที่ชำระตามเจตนารมณ์ในตัวอย่างจำนวนเต็ม Comment สามารถเปิดเผยนโยบายที่ตั้งใจไว้; ตรวจสอบว่าโค้ดนำไปปฏิบัติจริง
Identify text that is excluded from code
//เริ่ม comment ที่จบเมื่อจบบรรทัด/*เริ่ม block comment ที่จบเมื่อเจอ*/ถัดไป; block comment ไม่ซ้อนกัน ตัวแบ่งภายใน string literal เป็นข้อความ ดังนั้น"https://example.com"จึงไม่เริ่ม comment- ข้อความ comment ไม่ได้被执行เป็น Java statements การเพิ่มคำอธิบายแยกต่างหากทำให้ active expression คงเดิม; การวาง
//หน้าการกำหนดค่า active จะนำการกำหนดค่านั้นออกจากโค้ดที่คอมไพล์และอาจเปลี่ยนพฤติกรรม
Put Javadoc tags on separate lines
- A
/** ... */documentation comment ทันทีหน้าการประกาศสามารถถูกประมวลผลโดย Javadoc สรุปของมันอธิบายการทำงาน; บล็อกแท็กเช่น@paramและ@returnเริ่มบรรทัดใหม่หลังจากช่องว่างที่เลือกได้และ* - Class ครบถ้วนด้านล่างเอกสารรัศมีที่ไม่เป็นลบและคืนค่าพื้นที่วงกลม แท็กอธิบายอินพุตเอาต์พุตและอินพุตที่ถูกปฏิเสธ; Comment เพียงอย่างเดียวไม่บังคับ precondition ดังนั้นเมทโอดจึงตรวจสอบรัศมีที่เป็นลบอย่างชัดเจน
/** Circle-area calculations for finite radii. */
public class AreaDoc {
/**
* Returns the area of a circle for a finite radius.
* @param r the non-negative radius
* @return the area in squared radius units
* @throws IllegalArgumentException if r is negative
*/
public static double area(double r) {
if (r < 0) {
throw new IllegalArgumentException("Negative radius");
}
return Math.PI * r * r;
}
}
Javadocรับรู้ @param เป็นแท็กบล็อกเมื่อฝังอยู่ในข้อความสรุปบนบรรทัดเดียวกัน
Difficulty 1/5 · 100 coins + a small bonus on first completion today
แท็กบล็อกเริ่มบรรทัดของตัวเองหลังจากช่องว่างและดาวนำหน้าที่เป็นไปได้ ใช้(comment แบบหลายบรรทัดที่แสดง
Explain the decision a reader cannot see
- Comment ส่วนลดที่มีประโยชน์อาจระบุว่า "การชำระเงินคือ 90% ของราคาที่ระบุ; ตัวอย่างนี้ใช้ราคาคู่จำนวนเต็ม" สิ่งนี้อธิบายนโยบายและข้อสมมติ ในขณะที่
// multiply by 90merely重复 operation - การสรุปวิธีทำงานของฟังก์ชันสาธารณะมีประโยชน์แม้ว่าตัวฟังก์ชันจะสั้นก็ตาม: ผู้เรียกใช้ต้องการทราบสัญญาการใช้งานโดยไม่จำเป็นต้องศึกษาโค้ดภายใน ควรเลือกอธิบายที่เติมเต็มบริบทที่ขาดหายไปมากกว่าการตั้งข้อคิดเห็นว่าทุกคำอธิบายไม่จำเป็น
เมื่อโปรแกรม Java ทำงาน คอมเมนต์จะเป็น...
Difficulty 1/5 · 100 coins + a small bonus on first completion today
คอมเมนต์มีไว้สำหรับมนุษย์ — Java ข้ามไป
อะไรคือตัวเริ่มต้นคอมเมนต์แบบบรรทัดเดียวใน Java?
Difficulty 1/5 · 100 coins + a small bonus on first completion today
// 延伸至行尾; /* */ เป็น block
สไตล์คอมเมนต์哪种会被工具转换为 API documentation?
Difficulty 1/5 · 100 coins + a small bonus on first completion today
Javadoc /** */ with @param/@return generates API docs.
การเพิ่มคำอธิบายข้างสูตรที่แก้ไขแล้วไม่เปลี่ยนแปลงจะซ่อมแซมการคำนวณของมัน
Difficulty 1/5 · 100 coins + a small bonus on first completion today
ผิด: คำอธิบายไม่ใช่คำสั่ง การปิดการใช้งานคำสั่งด้วยเครื่องหมายแสดงว่าสามารถเปลี่ยนพฤติกรรมได้ แต่สิ่งนั้นเปลี่ยนโค้ดที่ใช้งานอยู่
คอมเมนต์ที่ดีอธิบาย WHY แทนที่จะบอกซ้ำสิ่งที่โค้ดทำได้ชัดเจน
Difficulty 1/5 · 100 coins + a small bonus on first completion today
คอมเมนต์ที่เจตนา ไม่ใช่สิ่งที่เห็นชัด
Check documentation against implementation
- สมมติว่าข้อความอธิบายสัญญาไว้ว่ารัศมีลบจะถูกปฏิเสธ แต่ตรวจสอบเงื่อนไขถูก ลบออก การเอกสารจึงเป็นข้อมูลเท็จแม้ว่าจะสร้างได้สำเร็จก็ตาม; ให้ทดสอบด้วยค่ารัศมีลบและรัศมีปกติ
- เมื่อพฤติกรรมเปลี่ยน ให้อัปเดตทั้งโค้ดภายใน ตรวจสอบ และเอกสารพร้อมกัน การสร้างหน้า API จะตรวจสอบแค่รูปแบบของเอกสารเท่านั้น ไม่ใช่ความถูกต้องของทุกข้อความในนั้น
/** Returns an area. @param r radius @return area */ ไม่วางแท็กบล็อกไว้ที่ต้นบรรทัดที่ต้องการ ใช้รูปแบบหลายบรรทัดด้านบน แล้วตรวจสอบส่วนพารามิเตอร์และค่าที่ส่งกลับที่ได้จากการสร้าง Comment อธิบายทั่วไปไม่ใช่การแก้ไขที่ทำงานได้จริง
คอมเมนต์ที่มีประโยชน์หรือไม่?
คอมเมนต์ที่ดีอธิบายเจตนา ไม่ใช่สิ่งที่เห็นชัด จัดกลุ่มแต่ละอัน
Predict a commented-out assignment
- เริ่มที่
int x = 1;เมื่อx = 5;เป็นสถานะเปิด การพิมพ์ x จะได้ 5; การแทนที่บรรทัดนั้นด้วย// x = 5;จะพิมพ์ 1 การเปลี่ยนว่า statementใดเป็นสถานะเปิดแตกต่างจากการเพิ่มหมายเหตุข้างๆ statementที่ไม่เปลี่ยนแปลง - ทบทวนคำถามทั้งสามข้อแยกกัน: การคำนวณที่เป็นสถานะเปิดถูกต้องหรือไม่ หมายเหตุอธิบายการคำนวณได้อย่างแม่นยำหรือไม่ และ Javadoc tags ถูก parse เข้าไปอยู่ในส่วนที่กำหนดไว้หรือไม่ การ compile ที่สำเร็จไม่ตอบทุกข้อ
_heading注释_อธิบายโค้ดให้กับผู้อ่าน Delimiters สามารถตัด statement ออกได้ แต่หมายเหตุข้างๆ โค้ดที่เป็นสถานะเปิดไม่สามารถแก้ไขการคำนวณได้ Javadoc block tags เริ่มต้นบนบรรทัดใหม่ ควรรักษาสัญญาการเอกสารให้สอดคล้องกับการนำไปใช้จริง
For a price of 100, type the amount paid after a ten percent discount.
Difficulty 1/5 · 100 coins + a small bonus on first completion today
The intended payment is 100−10=90. The misleading comment does not make the original expression calculate 90.
int x = 1; ตามด้วย // x = 5; บนบรรทัดแยกกัน ค่าของ x ที่พิมพ์ออกมาคืออะไร?
Difficulty 2/5 · 140 coins + a small bonus on first completion today
การมอบค่าให้ 5 ถูกตัดออกโดย_heading บรรทัดเดียว; x ยังคง 1