วิธีการจัดการกับความคิดเห็นซ้ำซากในความคิดเห็น? [ปิด]

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

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

(ตัวอย่าง C # แต่โปรดอ้างอิงคำถามว่าเป็นผู้ไม่เชื่อเรื่องภาษา)

ความคิดเห็นเช่นนั้นไร้ประโยชน์ ผมทำอะไรผิดหรือเปล่า? มันเป็นทางเลือกของชื่อที่ผิดหรือเปล่า? ฉันจะแสดงความคิดเห็นชิ้นส่วนเช่นนี้ดีกว่าได้อย่างไร ฉันควรจะข้ามความคิดเห็นสำหรับสิ่งเช่นนี้หรือไม่?

ในโครงการส่วนใหญ่ที่ฉันทำงานอยู่ไม่มีเวลาพอที่จะเขียนความเห็นอย่างละเอียดในสมาชิกชั้นเรียนทุกคน

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

โดยเฉพาะอย่างยิ่งเมื่อมีการใช้ข้อคิดเห็นของ Visual Studio ประกอบกับIntelliSenseเป็นความคิดที่ดีที่จะเริ่มต้นด้วยข้อมูลสั้น ๆ เกี่ยวกับฟิลด์:

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

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

class Example
{
    /// <summary>
    /// The Uri location where the update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

หากโปรแกรมเมอร์คนอื่นถามคุณเกี่ยวกับรายละเอียดในฟิลด์ให้อัพเดตความคิดเห็นด้วยข้อมูลนั้น:

ควรExample.UpdateLocationใช้การอัปเดตประเภทใดในการจัดเก็บ

class Example
{
    /// <summary>
    /// The Uri location where the Foo update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

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

และเช่นเดียวกับการเขียนโปรแกรมความคิดเห็นของคุณต้องเริ่มต้นที่ไหนสักแห่ง ความคิดเห็นที่มีความซ้ำซ้อนเป็นHello World!ความคิดเห็นในขณะที่คุณฝึกการเขียนและปรับปรุงเอกสารเอกสารเริ่มต้นของคุณจะมีความยืดหยุ่นมากขึ้นเรื่อย ๆ

ความคิดเห็นไม่ควรทำซ้ำรหัสของคุณ ความคิดเห็นไม่ควรตอบคำถาม " อย่างไร " แต่มีเพียง " ทำไม " และ " อะไร " เหตุใดจึงเลือกอัลกอริทึมสิ่งที่เป็นข้อสรุปโดยนัยที่นี่ (ยกเว้นภาษาของคุณมีพลังมากพอที่จะแสดงด้วยระบบประเภทสัญญาและเหมือนกัน) อะไรคือเหตุผลสำหรับการทำสิ่งนี้เลย ฯลฯ

ฉันขอแนะนำให้ดูการฝึกเขียนโปรแกรม Literate เพื่อหาแรงบันดาลใจ

ความคิดเห็นควรอธิบายถึงรหัสอย่าซ้ำซ้อน ความคิดเห็นส่วนหัวนี้ซ้ำกัน ทิ้งมันไว้

ปล่อยพวกเขาออกไป!

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

ใส่ไว้ใน!

ตัวอย่างของคุณแสดงข้อยกเว้นสองข้อสำหรับกฎนี้:

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

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

ฉันไม่เห็นด้วยอย่างยิ่งกับคำตอบที่ "ไม่ได้เขียนความคิดเห็น" ทำไม? ผมขอชี้ให้เห็นโดยการเปลี่ยนตัวอย่างของคุณเล็กน้อย

public Uri UpdateLocation ();

ดังนั้นฟังก์ชั่นนี้ทำอะไร:

• มันส่งคืน "ตำแหน่งการอัพเดท" หรือไม่? หรือ
• มัน "อัปเดต" ตำแหน่งและส่งคืนตำแหน่งใหม่หรือไม่

คุณสามารถเห็นว่าไม่มีความคิดเห็นมีความกำกวม ผู้มาใหม่สามารถทำผิดพลาดได้อย่างง่ายดาย

ในตัวอย่างของคุณเป็นคุณสมบัติดังนั้นเมธอด "get / set" เปิดเผยว่าตัวเลือกที่สองนั้นไม่ถูกต้องและมันหมายถึง "สถานที่ตั้ง" และไม่ใช่ "อัปเดตตำแหน่ง" แต่มันง่ายเกินไปที่จะทำผิดพลาดโดยเฉพาะในกรณีของคำที่ไม่ชัดเจนเช่น "update" เล่นอย่างปลอดภัย. อย่าสับสนคนใหม่เพียงแค่นี้เพื่อประหยัดเวลาของคุณไม่กี่วินาที

/// <summary>บล็อกจะใช้ในการสร้างเอกสารIntelliSenseและเอกสาร API

ดังนั้นหากนี้เป็นสาธารณะ API คุณควรเสมอรวมอย่างน้อย<summary>ความคิดเห็นแม้ว่าวัตถุประสงค์ของฟังก์ชั่นที่ควรจะชัดเจนในตัวเองให้กับผู้อ่าน

อย่างไรก็ตามนี่เป็นข้อยกเว้นของกฎ โดยทั่วไปก็อย่าลืมแห้ง (ไม่ซ้ำตัวเอง)

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

_{สำหรับฉันกรณีของผลประโยชน์ที่ชัดเจนคือเมื่อมีการตรวจสอบอัตโนมัติสำหรับความคิดเห็นที่ขาดหายไปและฉันใช้การตรวจสอบนั้นเพื่อตรวจสอบรหัสที่จำเป็นต้องกรอกข้อมูลสำคัญ ด้วยเหตุนี้ฉันจึงเติมตัวยึดตำแหน่งบางตัว - เพียงเพื่อให้แน่ใจว่ารายงานเครื่องมือไม่มี "การเตือนที่ผิดพลาด"}

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

สำหรับตัวอย่างเฉพาะนี้ฉันจะใช้บางอย่างของ "ชนิดอธิบายตนเอง" (สมมติว่าไม่ใช่กรณีที่การลบออกจะทำงาน) เช่นนั้น:

class Example
{
    /// <summary>
    /// Self descriptive method name.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

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

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

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

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

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

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

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

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

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

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

ในรหัสของฉันฉันมักจะแสดงความคิดเห็นซ้ำซากในสถานที่รวมถึงคนที่น่าเกรงขามเช่น:

<?php
// return the result
return $result;
?>

... ซึ่งเห็นได้ชัดว่ามีส่วนช่วยเพียงเล็กน้อยในการทำให้โค้ดเข้าใจได้ง่ายขึ้นจากมุมมองที่อธิบายได้

ในใจของฉันแม้ว่าความคิดเห็นเหล่านี้ยังคงมีค่าถ้าพวกเขาช่วยในการรักษาความมั่นคงภาพของรูปแบบสีในเน้นไวยากรณ์ของคุณ

ฉันคิดว่าโค้ดมีโครงสร้างที่คล้ายกับภาษาอังกฤษมากโดยมี "ประโยค" และ "ย่อหน้า" (แม้ว่า "ย่อหน้า" อาจประกอบด้วยประโยคเดียวทั้งหมด) ฉันมักจะรวมตัวแบ่งบรรทัดและสรุปหนึ่งบรรทัดข้างต้น "ย่อหน้า" แต่ละรายการ ตัวอย่างเช่น:

<?php
//get the id of the thing
$id = $_POST['id'];

//query the things out of the the database
$things = array();
$result = mysql_query("SELECT * FROM Things WHERE `id` = $id");
while ($row = mysql_fetch_assoc($result)) {
    //create a proper Thing object or whatever
    $things[] = new Thing($row);
}

//return the things
return $things;
?>

(ไม่ต้องสนใจรหัสที่ไม่สมบูรณ์การฉีด SQL ฯลฯ คุณจะได้รับแนวคิดนี้)

สำหรับฉันความคิดเห็นสุดท้ายอย่างแท้จริงเพิ่มมูลค่าให้กับรหัสเพียงเพราะมันช่วยให้มองเห็น "ย่อหน้า" หนึ่งย่อหน้าจากที่อื่นโดยการรักษารูปแบบการระบายสีที่สอดคล้องกัน

ความคิดเห็นควรใช้เพื่อทำสิ่งใดสิ่งหนึ่งต่อไปนี้

1. ข้อมูลสำหรับเครื่องกำเนิดเอกสารที่จะคว้า สิ่งนี้ไม่สามารถอธิบายได้สิ่งนี้มีความสำคัญอย่างยิ่ง
2. คำเตือนว่าทำไมโค้ดบางส่วนถึงเป็นแบบนั้นและข้อควรพิจารณาอื่น ๆ ฉันจัดการกับโค้ดที่เขียนด้วยภาษาการเขียนโปรแกรม 2 ภาษา ส่วนสำคัญอย่างหนึ่งของสิ่งนี้คือการมีโครงสร้างร่วมกันระหว่างสองภาษา ความคิดเห็นที่สถานที่ทั้งสองแห่งแจ้งให้ผู้ใช้ทราบว่าหากพวกเขาเปลี่ยนหมายเลขนี้พวกเขายังต้องเปลี่ยนอีกคนหนึ่งซึ่งเป็นประโยชน์อย่างมาก
3. เขียนบันทึกเพื่ออธิบายว่าทำไมโค้ดที่ดูแปลก ๆ โดยเฉพาะนั้นเป็นอย่างไร หากคุณต้องคิดว่าจะให้โค้ดทำงานในลักษณะใดและวิธีการแก้ปัญหาไม่ชัดเจนตั้งแต่ต้นอาจเป็นคำอธิบายที่คุ้มค่าสำหรับสิ่งที่คุณพยายามทำ
4. การติดฉลากอินพุต / เอาท์พุตหากยังไม่ชัดเจน เป็นเรื่องดีเสมอที่จะรู้ว่าอินพุตของคุณคาดว่าจะเป็นรูปแบบใดและอยู่ในรูปแบบใด

ไม่ควรใช้ความคิดเห็นเพื่อทำสิ่งต่อไปนี้:

1. อธิบายสิ่งต่าง ๆ ที่ชัดเจนอย่างยิ่ง page=0; // Sets the page to 0ผมเคยเห็นรหัสเดิมเช่นนี้ ฉันคิดว่าบุคคลที่มีความสามารถจะคิดออก

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

property UpdateLocation:TUpdateLocation;  // url="http://x/y/3.2/upd.aspx",proto=http

ตอนนี้ฉันรู้ว่ามีอะไรเกิดขึ้นที่นั่นและจากความคิดเห็นฉันมีความคิดที่ชัดเจนว่าจะใช้มันอย่างไร

ฉันจะบอกว่ามันขึ้นอยู่กับวัตถุประสงค์ของความคิดเห็น

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

หากความคิดเห็นจะสร้างเอกสารสำหรับทีมที่อยู่ห่างไกลทางภูมิศาสตร์ฉันก็จะเอาเอกสารทุกฉบับไปไว้ที่นั่น

ฉันคิดว่าหัวข้อนี้มีการพูดคุยกันอย่างกว้างขวางภายใต้ชื่อเช่น "ความคิดเห็น: รูปแบบการต่อต้าน" หรือ "มีความคิดเห็นกลิ่นรหัส?" ( ตัวอย่างหนึ่ง )

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

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

หากคุณสามารถเขียนโค้ดที่ไม่ต้องการคอมเม้นต์ได้แสดงว่าคุณประสบความสำเร็จในการเขียนโปรแกรมนิพพาน!

ความคิดเห็นที่น้อยกว่าโค้ดของคุณต้องการโค้ดที่ดีกว่า!

ความคิดเห็นเช่นนั้นไร้ประโยชน์ ผมทำอะไรผิดหรือเปล่า?

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

เอกสารประกอบที่รวบรวมโดยอัตโนมัติรหัสควรเอกสารตัวเองเพื่อให้ความคิดเห็นควรเอกสารเฉพาะที่รหัสไม่เพียงพอที่จะเอกสารตัวเอง

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