การเขียนเอกสารสำหรับวิธีการที่เข้าใจกันดีเช่นเท่ากับใน Java

10

เป็นการดีหรือไม่ที่จะเขียนข้อคิดเห็นสำหรับวิธีที่รู้จักกันอย่างกว้างขวางเช่นเท่ากับ, เปรียบเทียบกับ ฯลฯ ?

พิจารณารหัสด้านล่าง

 /**
 * This method compares the equality of the current object 
  with the object of same type
 */
@Override
public boolean equals(Object obj) {

               //code for equals

     }

บริษัท ของฉันคลั่งไคล้ในการแสดงความคิดเห็นเช่นเดียวกับข้างต้นต้องใช้ความเห็น Javadoc ข้างต้นหรือไม่ มันไม่ชัดเจนและเข้าใจดีว่าวิธีการที่เท่าเทียมและชอบ (เปรียบเทียบ, เปรียบเทียบกับ) ฯลฯ ทำอย่างไร?

คุณมีข้อเสนอแนะอะไร?

java comments

— Vinoth Kumar CM
แหล่งที่มา

3

ความคิดเห็นปัจจุบันของคุณไม่ถูกต้อง ลายเซ็นวิธีการของคุณถูกต้องในการรับวัตถุทั่วไป แต่ความคิดเห็นของคุณระบุว่า 'วัตถุชนิดเดียวกัน'

— c_maker

4

ฉันอยากเห็นความคิดเห็นที่อธิบายความเท่าเทียมกันสำหรับวัตถุนี้ "ความเท่าเทียมกัน" เป็นคำที่ลื่น ใน Common Lisp มีฟังก์ชันความเสมอภาคมากมายและคุณเลือกฟังก์ชันที่เหมาะสมเมื่อใช้งาน

— David Thornley

ในกรณีนี้ฉันหมายถึงวัตถุสองชิ้นที่เท่ากันใน "วิธีที่มีความหมาย" ตัวอย่างเช่นสองวัตถุของพนักงานมีค่าเท่ากันถ้าพวกเขามีรหัสพนักงานเดียวกันแทนที่จะบอกว่าพวกเขาสวมเสื้อสีเดียวกัน

— Vinoth Kumar CM

6

@Vinoth: "วิธีการที่มีความหมาย" เป็นสิ่งที่คุณต้องการในการบันทึกเอกสาร :)

— c_maker

6

JavaDoc สนับสนุนการสืบทอดความคิดเห็นแล้ว ตามเอกสาร "ตัวสร้างฟิลด์และคลาสที่ซ้อนกันจะไม่ได้รับความคิดเห็นจาก doc" แต่จะมีวิธีการเช่นequals()นั้น เนื่องจากObjectคลาสมีequals()วิธีการที่มีเอกสารครบถ้วนคุณควรจะสามารถสืบทอดเอกสารนั้นได้โดยไม่มีปัญหา

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

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

— โทมัสโอเวนส์
แหล่งที่มา

ฉันรู้เกี่ยวกับการสืบทอด แต่ บริษัท "มอบอำนาจ" ให้เราเขียนเอกสารจาวาอย่างชัดเจน

— Vinoth Kumar CM

3

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

— Thomas Owens

@ โทมัส: มีการให้อภัยมากกว่าที่จะถามตัวเลือกการอนุญาต: เพียงแค่โค้งงอเงียบ ๆ และดูว่ามีใครบ่น

— dsimcha

@dsimcha บางที แต่ถ้าซ้ำแล้วซ้ำอีกมันอาจไม่ดีสำหรับงาน นี่ไม่ใช่สิ่งเดียวหรือสองอย่าง

— Thomas Owens

9

ในทีมของฉันเรามักจะใช้@inheritDocคำอธิบายประกอบสำหรับequals()และhashcode()ฉันหวังว่าเราจะไม่ได้

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

เป็นการดีที่จะบันทึกว่าคุณลักษณะใดมีส่วนร่วมในวิธีการและอย่างน้อยก็อาจเป็นสาเหตุ

— c_maker
แหล่งที่มา

1

คำสั่งสุดท้ายของคุณคือเหตุผลที่ดีที่สุดสำหรับการจัดทำเอกสารด้วยตนเอง อธิบายสิ่งที่กำลังทำ แน่ใจว่าเท่ากัน () อาจเปรียบเทียบทุกองค์ประกอบในชั้นเรียนหรือคุณอาจต้องการให้มันเพียงแค่เปรียบเทียบทุกเขตข้อมูลสตริงหรืออย่างอื่น

— นิโคลัส

2

โปรดจำไว้ว่าความคิดเห็นช่วยให้นักพัฒนาทุกประเภทหากพวกเขาถูกต้อง

ปัญหาคือบางครั้งพวกเขาไม่สมบูรณ์และไม่ถูกต้อง

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

การแสดงวิธีการวัตถุประสงค์กฎและอื่น ๆ ในความคิดเห็น "มีประโยชน์และมีความหมาย" เป็นสิ่งที่ดี

— ไม่มีโอกาส
แหล่งที่มา

2

มันเป็นวิธีปฏิบัติที่แย่มากในการทิ้งขยะรหัสที่มีความคิดเห็นที่ว่างเปล่าเช่น:

/**
 * This method compares the equality of the current object with the object of same type...
 */

สิ่งนี้บอกว่าไม่มีประโยชน์ ยิ่งแย่ไปกว่านั้นมันมีทั้งสไตล์และไวยากรณ์ที่แย่:

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

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

public class Fraction {
  private int numerator, denominator;
  /**
   * @return true if <i>this</i> is numerically equal to <i>other</i>
   */
  public boolean equals(Fraction other) {
    return numerator * other.denominator == other.numerator * denominator;
  }
...
}

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

— เควินไคลน์
แหล่งที่มา

1

มาตรฐานการเข้ารหัสของเรากำหนดว่าเมื่อแทนที่วิธีการนั้นไม่จำเป็นต้องทำเอกสารเว้นแต่ในการลบล้างเอกสารในชั้นผู้ปกครองหรือส่วนต่อประสานนั้นไม่แม่นยำและครอบคลุมอีกต่อไปสำหรับชั้นย่อยหรือการนำไปปฏิบัติ

สำหรับเท่ากับเราอาจต้องการทราบว่าการเปรียบเทียบจะทำเฉพาะในคีย์หลักเมื่อเปรียบเทียบเอนทิตีที่ได้รับการสนับสนุนฐานข้อมูลเนื่องจากไม่สอดคล้องกับเอกสารประกอบObject.equals()ทั้งหมด

— คริส
แหล่งที่มา

0

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

— ปีเตอร์เทย์เลอร์
แหล่งที่มา

0

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

นอกจากนี้ฉันจะบอกว่าถ้ารหัสที่คุณกำลังสร้าง / แก้ไขไม่ได้เป็นสำหรับสาธารณะ API แล้วเพียงแค่ทิ้ง javadocs สำหรับวิธีการทั่วไปเพราะสิ่งเหล่านี้จะเพิ่มความยุ่งเหยิงและเสียงรบกวน

— บ๊อบซานโตส
แหล่งที่มา