“ ฉัน”,“ เรา”, หรือไม่อยู่ในเอกสารรหัส

ฉันพบว่าตัวเองเขียน (หวังว่า) ความคิดเห็นที่เป็นประโยชน์ในรหัส (C ++) เอกสารประเภท:

The reason we are doing this is...

เหตุผลที่ฉันใช้ "พวกเรา" แทนที่จะเป็น "ฉัน" ก็เพราะฉันเขียนบทความเชิงวิชาการจำนวนมากซึ่งบ่อยครั้งที่ "เรา" ชอบ

ดังนั้นนี่คือคำถาม มีเหตุผลที่ดีที่จะเลือกใช้รหัสอื่นในรหัสเอกสารหรือไม่:

1. ใช้ "เรา":เหตุผลที่เราทำเช่นนี้คือ ...
2. ใช้ "ฉัน":เหตุผลที่ฉันทำสิ่งนี้คือ ...
3. ใช้ชื่อของฉัน:เหตุผล[my name]นี้คือ ...
4. เสียงไม่โต้ตอบ:เหตุผลที่ทำเช่นนี้คือ ...
5. ไม่:ทำอย่างนี้เพราะ ...

ฉันเลือก # 1 เพราะฉันคุ้นเคยกับการเขียนด้วยวิธีนี้ แต่เอกสารไม่ใช่สำหรับนักเขียน แต่สำหรับผู้อ่านดังนั้นฉันจึงสงสัยว่าการเพิ่มชื่อนักพัฒนาซอฟต์แวร์นั้นมีประโยชน์หรือไม่ จะมีการเปลี่ยนแปลงเมื่อรักษารหัส

ฉันจะไปกับ:

# 6 ประกาศ: ...

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

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

// The reason this was done is to prevent null pointer exceptions later on.

ฉันจะพูดว่า:

// Frobnicate the widget first so foo can never be null.

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

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

นี่คือตัวอย่างที่ฉันคิดว่าแสดงให้เห็นถึงจุด

/// <summary>
/// Takes data from the remote client and stores it in the database.
/// </summary>
/// <param name="data">The data to store.</param>
public void StoreData(ComplexObject data)
{
    // Don't take candy from strangers
    ComplexObject safeData = SanitizeData(data);
    ...
}

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

1. ความคิดเห็นจะไม่เปลี่ยนแปลงเสมอเมื่อมีการเปลี่ยนแปลงรหัสซึ่งอาจทำให้เกิดความสับสนในภายหลัง

2. การทดสอบหน่วยทำให้ผู้ดูแลง่ายขึ้นในการเล่นกับรหัส การเรียนรู้ codebase ใหม่นั้นง่ายกว่ามากหากคุณมีหน่วยที่คุณสามารถหยุดเพื่อสังเกตการเปลี่ยนแปลง

แม้ว่าถนนสายนี้ต้องการงานมากขึ้นการทดสอบหน่วยสามารถเป็นรูปแบบที่ดีของเอกสาร

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

ฉันเกลียดที่จะกีดกันใครบางคนจากการแสดงความคิดเห็นรหัสของพวกเขาเพราะพวกเขากังวลเกี่ยวกับกรณีความเครียดและสรรพนามของพวกเขา

เหตุผลที่ฉันใช้ "พวกเรา" แทนที่จะเป็น "ฉัน" ก็เพราะฉันเขียนบทความเชิงวิชาการจำนวนมากซึ่งบ่อยครั้งที่ "เรา" ชอบ

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

สำหรับคำถามเฉพาะของคุณ: ฉันจะไม่แสดงความคิดเห็นดังกล่าวเว้นแต่ว่าจะเริ่มต้นด้วย:

// TODO: clean this up, ...

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