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

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

ตกลงฉันจะเริ่ม

1. โดยปกติแล้วฉันไม่ได้ใช้/* */ความคิดเห็นแม้ว่าฉันจะต้องแสดงความคิดเห็นหลายบรรทัด

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

   ข้อเสีย : ยากที่จะแก้ไขรหัสดังกล่าวโดยไม่ต้อง IDE

2. วาง "จุด" ไว้ท้ายความคิดเห็นที่เสร็จแล้ว

   ตัวอย่างเช่น:

   //Recognize wallpaper style. Here I wanted to add additional details
   int style = int.Parse(styleValue);
   //Apply style to image.
   Apply(style);
   

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

3. จัดข้อความในการแจกแจงพารามิเตอร์การแสดงความคิดเห็น ฯลฯ

   ตัวอย่างเช่น:

   public enum WallpaperStyle
   {
       Fill = 100,     //WallpaperStyle = "10"; TileWallpaper = "0".
       SizeToFit = 60, //WallpaperStyle = "6";  TileWallpaper = "0".
       Stretch = 20,   //WallpaperStyle = "2";  TileWallpaper = "0".
       Tile = 1,       //WallpaperStyle = "0";  TileWallpaper = "1".
       Center = 0      //WallpaperStyle = "0";  TileWallpaper = "0".
   };
   

   ข้อดี : ดูดีขึ้นและมองเห็นได้ง่ายขึ้นเพื่อค้นหาสิ่งที่คุณต้องการ

   ข้อเสีย : ใช้เวลาในการจัดแนวและแก้ไขให้ยากขึ้น

4. เขียนข้อความในความคิดเห็นที่คุณไม่สามารถรับได้โดยการวิเคราะห์รหัส

   ตัวอย่างเช่นความคิดเห็นที่โง่:

   //Apply style.
   Apply(style);
   

   ข้อดี : คุณจะมีรหัสที่ชัดเจนและเล็กด้วยข้อมูลที่เป็นประโยชน์ในการแสดงความคิดเห็น

ข้อความด้านล่างบางข้อความเป็นเรื่องส่วนตัวแม้ว่าจะมีเหตุผลและมีความหมายที่จะเป็นเช่นนี้

ประเภทความคิดเห็น

สำหรับรุ่นสั้น ๆ ... ฉันใช้ความคิดเห็นสำหรับ:

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

อ่านรายละเอียดด้านล่างและเหตุผล (อาจปิดบัง) ด้านล่าง

ความคิดเห็นต่อท้าย

ขึ้นอยู่กับภาษาทั้งการใช้ความคิดเห็นแบบบรรทัดเดียวหรือความคิดเห็นแบบหลายบรรทัด ทำไมมันขึ้นอยู่กับ? มันเป็นเพียงปัญหามาตรฐาน เมื่อฉันเขียนรหัส C, ฉันโปรดปรานสมัยเก่ารหัส ANSI C89 /* comments */โดยค่าเริ่มต้นดังนั้นฉันชอบที่จะมักจะมี

ดังนั้นฉันจะมีสิ่งนี้ใน C เวลาส่วนใหญ่และบางครั้ง (ขึ้นอยู่กับสไตล์ของ codebase) สำหรับภาษาที่มีไวยากรณ์คล้าย C:

typedef struct STRUCT_NAME {
  int fieldA;                /* aligned trailing comment */
  int fieldBWithLongerName;  /* aligned trailing comment */
} TYPE_NAME;

Emacs M-;เป็นสิ่งที่ดีและไม่ว่าสำหรับฉันด้วย

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

ความคิดเห็นหลายสาย

ฉันไม่เห็นด้วยกับกฎเกณฑ์ของคุณโดยใช้ความคิดเห็นแบบบรรทัดเดียวสำหรับเรื่องนี้น่าสนใจยิ่งขึ้น ฉันใช้สิ่งนี้:

/*
 * this is a multi-line comment, which needs to be used
 * for explanations, and preferably be OUTSIDE the a
 * function's or class' and provide information to developers
 * that would not belong to a generated API documentation.
 */

หรือสิ่งนี้(แต่ฉันทำไม่ได้บ่อยกว่านั้นยกเว้นใน codebase ส่วนบุคคลหรือส่วนใหญ่เป็นประกาศเกี่ยวกับลิขสิทธิ์ - นี่คือประวัติศาสตร์สำหรับฉันและมาจากภูมิหลังทางการศึกษาของฉัน แต่น่าเสียดายที่ IDEs ส่วนใหญ่สับสนเมื่อใช้รูปแบบอัตโนมัติ) :

/*
** this is another multi-line comment, which needs to be used
** for explanations, and preferably be OUTSIDE the a
** function's or class' and provide information to developers
** that would not belong to a generated API documentation.
*/

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

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

try {
  /* you'd have real code here, not this comment */
} catch (AwaitedException e) {
  /*
   * Nothing to do here. We default to a previously set value.
   */
}

ซึ่งน่าเกลียดอยู่แล้วสำหรับฉัน แต่ฉันจะทนในบางสถานการณ์

ความคิดเห็นเอกสาร

& Javadoc อัล

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

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

รหัสออกความคิดเห็น

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

แต่เมื่อฉันต่อต้านโค้ดที่ใส่ความเห็นใน SCM นั้นมักจะสั้นมากเพราะฉันจะลบชิ้นที่ถูกคอมเม้นต์ออกก่อนที่จะทำ (อ่านคำตอบสำหรับคำถามนี้ที่"แก้ไขโดยความเห็นในบรรทัดและ SCM" )

สไตล์ความคิดเห็น

ฉันมักจะเขียน:

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

หมายเหตุเกี่ยวกับการเขียนโปรแกรมความรู้

คุณอาจต้องการที่จะได้รับความสนใจในความรู้ด้านการเขียนโปรแกรมเป็นที่รู้จักในนี้กระดาษโดยโดนัลด์ Knuth

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

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

เป็นหมายเหตุด้านและตัวอย่าง: กรอบ JavaScript underscore.jsแม้ว่าจะไม่สอดคล้องกับสไตล์การแสดงความคิดเห็นของฉันเป็นตัวอย่างที่ดีของcodebase ที่มีเอกสารที่ดีและแหล่งที่มีคำอธิบายประกอบที่ดีแต่อาจไม่ใช่วิธีที่ดีที่สุดที่จะใช้เป็น การอ้างอิง API)

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

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

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

public void Login(string username, string password)
{
    // Get the user entity
    var user = userRepository.GetUser(username);


    // Check that the user exists
    if (user == null)
    {
        throw new UserNotFoundException();
    }

    // Check that the users password matched
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }

    //Check that the users account has not expired
    if (user.Expired)
    {
        throw new UserExpiredException();
    }

    //Mark user as logged in
    ...
}

สิ่งนี้สามารถอ่านซ้ำกับสิ่งที่อ่านได้ง่ายกว่าและอาจนำมาใช้ซ้ำได้:

public void Login(string username, string password)
{
    var user = GetUserForUsername(username);

    CheckUsersPasswordMatched(user, password);

    CheckUserAccountNotExpired(user);

    MarkUserAsLoggedIn(user);
}

private void User GetUserForUsername(string username)
{
    var user = userRepository.GetUser(username);

    if (user == null)
    {
        throw new UserNotFoundException();
    }
    return user;
}

private void CheckUsersPasswordMatched(User user, string password)
{
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }
}

private void CheckUserAccountNotExpired(User user)
{
    if (user.Expired)
    {
        throw new UserExpiredException();
    }
}

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

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

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

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

//Apply style.

Apply(style);

ควรจะเป็น

// Unlike the others, this image needs to be drawn in the user-requested style apply(style);

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

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

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

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

/** 
 * This is an example, how to waste vertical space,
 * and how to use useless asterixes.
 */

สองเส้นน้อยกว่า:

/** This is an example, how to spare vertical space,
    and how to avoid useless asterixes. */

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

คุณยังสำรองไบต์บางส่วนถ้าคุณใช้แท็บสำหรับการเยื้อง

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

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

// 05-24-2011 (John Doe): Changed this method to use Foo class instead of Bar

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

// (John Doe) 05-24-2011 not sure why we are using this object?
FooBar oFooBar = Quux.GetFooBar(iFooBarID, bSomeBool);
oFooBar.DiscombobulateBaz();

// (John Doe). This method is poorly named, it's used for more 
// than just frazzling arvadents
public int FrazzleArvadent(int iArvadentID)

1. เลือกระบบเอกสารเช่น doxygenและติดกับมัน ทำการตรวจสอบเอกสารที่ผลิตต่อไป
2. ลองนึกภาพคนใหม่ที่เข้ามาในฐานรหัสและอ่านเอกสารของคุณพวกเขาจะเริ่มต้นใช้งานได้หรือไม่? นักศึกษาฝึกงานนั้นดีสำหรับเรื่องนี้นั่งลงใหม่พร้อมฐานเอกสารที่มีอยู่ของคุณและงานง่าย ๆ และดูว่าพวกเขาจะไปได้ไกลแค่ไหนถ้าพวกเขาสะดุดสิ่งใดที่คุณบอกให้พวกเขาทำต่อไปในเอกสาร
3. ทำเอกสารประกอบการตรวจสอบจุดตรวจในกระบวนการตรวจสอบของคุณ

ผู้อ่านรหัสมักจะพยายามตอบคำถามสามข้อ:

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

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

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