การแสดงความคิดเห็น / รูปแบบเอกสารในรหัส

นี่อาจเป็นคำถามที่โง่ แต่ก็อยู่ข้างหลังศีรษะของฉันซักพักแล้วและฉันไม่สามารถหาคำตอบที่เหมาะสมได้จากที่อื่น

ฉันมีครูผู้หนึ่งที่บอกว่าเราควรระบุพารามิเตอร์แต่ละรายการด้วยคำอธิบายอย่างชัดเจนแม้ว่าจะมีเพียงพารามิเตอร์เดียวเท่านั้น สิ่งนี้นำไปสู่การซ้ำซ้อนมากมาย:

double MyFunction(const int MyParam);
// Function: MyFunction
// Summary: Does stuff with MyParam.
// Input: int MyParam - The number to do stuff with.
// Output: MyParam with stuff done to it.

เมื่อเขียนเอกสารในโค้ดคุณมีรายละเอียดมากน้อยเพียงใด?

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

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

^{1: บางคนที่คุ้นเคยกับภาษาที่เขียนโค้ดอย่าเขียนความเห็นเพื่อสอนแสดงความคิดเห็นเพื่อเสริมข้อมูล}

หลายภาษามีคุณสมบัติการสร้างเอกสาร API เช่น Ruby, Java, C # และ C ++ (ผ่านเครื่องมือบรรทัดคำสั่ง) เมื่อคุณคิดอย่างนั้นมันทำให้การเขียนเอกสาร API มีความสำคัญมากกว่า ท้ายที่สุดก็ตอบคำถาม "ฉันจะทำอย่างไร ... ?" ดังนั้นฉันจะไม่ทำอะไรซ้ำ ๆ เหมือนFunction: MyFunctionเมื่อชื่อของฟังก์ชันนั้นชัดเจนสำหรับทุกคนที่เห็น เครื่องมือสร้างเอกสาร API นั้นฉลาดพอที่จะทำสิ่งนั้นให้ฉันได้ อย่างไรก็ตามรายละเอียดต่อไปนี้มีประโยชน์โดยเฉพาะอย่างยิ่งในวิธีการ / ฟังก์ชั่นสาธารณะ:

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

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

หากเป็นภาษาที่ไม่มีคุณลักษณะเหล่านี้ความคิดเห็นจะช่วย แต่ไม่มากเท่านั้น

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

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

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

นั่นคล้ายกับวิธีที่กรอบงานส่วนใหญ่ -Doc แยกวิเคราะห์เอกสารในโค้ด (JavaDoc, PHPDoc เป็นต้น)

จาก Java สร้างอัตโนมัติโดย IDE:

/**
 * [Description]
 * @param str [Description]
 * @param isCondition [Description]
 * @return [Description]
 */
public int testFunction(String str, boolean isCondition) {
    ...
}

นี่เป็นรูปแบบเดียวกับที่ใช้สร้างเอกสารสำหรับคุณสมบัติภาษาในตัว - ตัวอย่าง: http://download.oracle.com/javase/6/docs/api/java/lang/String.html

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

บิตเดียวที่ฉันมักจะพบค่อนข้างซ้ำซ้อนคือคำอธิบายการส่งคืน - โดยปกติแล้วมันเกือบจะเหมือนกับคำอธิบายวิธีการของฉัน

มีจุดประสงค์สองประการสำหรับความคิดเห็น:

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

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

a += 1; //adds 1 to the value in a

จริงๆ? ขอบคุณ! ฮ่า ๆ

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

/*
* Finds all the locations where you have access to for this client and returns them in an array .
* @author Radu
* @version 1.0
* @param int $id ( The id of the client for which you're requesting access. )
* @param object $db ( A resource of type Mysql, representing a connection to mysql database, if not supplied the function will connect itself. )
* @return array ( Returns array with id's of locations that you are allowed to see, an empty array if you do not have acces to any locations or returns FALSE and triggers a Warning if any error occuread )
* @use array allowed_locations ( $id [, $db] )
*/
function allowed_locations($id, $db=NULL){ ... }

และเช่นเดียวกับ @ Larry Coleman กล่าวว่าความคิดเห็นแบบอินไลน์ควรบอกว่าทำไมคุณถึงทำโค้ดบางส่วน

$funcResult = SomeFunction();
if(is_array($funcResult))
{    //Beacause SomeFunction() could return NULL, and count(NULL) = 1
    $c = count($funcResult);
} else {
    $c = 0;
}
if($c == 1)
{
 ... 
}else
{
 ...
}

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

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

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