ทำความสะอาดรหัสความคิดเห็นเกี่ยวกับเอกสารประกอบคลาส

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

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

public Product GetById(int productId) {...}

ฉันกำลังเพิ่มสรุปวิธีการดังต่อไปนี้

/// <summary>
/// Retrieves a product by its id, returns null if no product was found.
/// </summary

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

อย่างไรก็ตามเพื่อนร่วมงานของฉันคิดว่าข้อคิดเห็นเหล่านี้เป็น " กลิ่นรหัส " และ "ความคิดเห็นมักจะล้มเหลว" ( Robert C. Martin )

มีวิธีในการแสดงและสื่อสารความรู้ประเภทนี้โดยไม่เพิ่มความคิดเห็นหรือไม่? เนื่องจากฉันเป็นแฟนตัวยงของ Robert C. Martin ฉันรู้สึกสับสนเล็กน้อย บทสรุปเหมือนกันกับความคิดเห็นและดังนั้นจึงล้มเหลวเสมอ?

นี่ไม่ใช่คำถามเกี่ยวกับความคิดเห็นในบรรทัด

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

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

ดึงผลิตภัณฑ์ตาม id

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

ส่งคืนค่า null หากไม่พบผลิตภัณฑ์

Ah! นั่นคือสิ่งที่เราไม่สามารถทราบได้อย่างแน่นอนจากลายเซ็นและให้ข้อมูลที่เป็นประโยชน์

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

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

เกี่ยวกับกรณีนี้โดยทั่วไปปัญหา null เป็นที่รู้จักกันดีว่าเป็นเรื่องยาก มีเหตุผลฐานรหัสเกลื่อนไปด้วยคำสั่งยามทำไมการตรวจสอบโมฆะเป็นเงื่อนไขที่นิยมสำหรับสัญญารหัสทำไมการดำรงอยู่ของโมฆะได้รับการเรียกว่า "ผิดพันล้านดอลลาร์" มีตัวเลือกที่ทำงานได้ไม่มาก หนึ่งที่ได้รับความนิยมแม้ว่าพบใน C # เป็นTry...แบบแผน:

public bool TryGetById(int productId, out Product product);

ในภาษาอื่น ๆ มันอาจเป็นสำนวนที่จะใช้ประเภท (มักเรียกสิ่งที่ชอบOptionalหรือMaybe) เพื่อระบุผลลัพธ์ที่อาจจะใช่หรือไม่:

public Optional<Product> GetById(int productId);

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

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

คำพูดของ Robert C. Martin ถูกนำออกจากบริบท นี่คือคำพูดที่มีบริบทอีกเล็กน้อย:

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

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

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

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

(คัดลอกมาจากที่นี่แต่ข้อความต้นฉบับมาจากClean Code: คู่มือของงานฝีมือซอฟต์แวร์ Agile )

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

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

หากคุณต้องการหลีกเลี่ยงความจำเป็นของความคิดเห็นคุณต้องลบปัญหาพื้นฐาน (ซึ่งเป็นการใช้nullเป็นค่าส่งคืนที่ถูกต้อง) โดยทำให้ API ชัดเจนยิ่งขึ้น ตัวอย่างเช่นคุณสามารถส่งคืนประเภทบางOption<Product>ประเภทได้ดังนั้นลายเซ็นประเภทจะสื่อสารอย่างชัดเจนว่าจะส่งคืนอะไรในกรณีที่ไม่พบผลิตภัณฑ์

แต่ในกรณีใด ๆ มันไม่เป็นความจริงที่จะจัดทำเอกสาร API อย่างสมบูรณ์เพียงแค่ใช้ชื่อเมธอดและลายเซ็นชนิด ใช้ doc-comments สำหรับข้อมูลที่ไม่ชัดเจนเพิ่มเติมซึ่งผู้ใช้ควรทราบ รับเอกสาร API จากDateTime.AddMonths()ใน BCL:

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

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

ความคิดเห็นแบบอินไลน์ก็ไม่เลวเช่นกัน

Badความคิดเห็นที่ไม่ดี ตัวอย่างเช่นความคิดเห็นที่อธิบายสิ่งที่สามารถมองเห็นได้เพียงเล็กน้อยจากโค้ดตัวอย่างคลาสสิก ได้แก่ :

// increment x by one
x++;

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

// data1 is the collection of tasks which failed during execution
var data1 = getData1();

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

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

// need to reset foo before calling bar due to a bug in the foo component.
foo.reset()
foo.bar();

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

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

มีความแตกต่างระหว่างคือการแสดงความคิดเห็นรหัสของคุณและการจัดเก็บเอกสารรหัสของคุณ

• ความคิดเห็นที่จำเป็นในการรักษารหัสในภายหลังนั่นคือการเปลี่ยนรหัสเอง

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

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

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

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

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

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

ดังนั้นเพื่อนร่วมงานของคุณผิดทั้งหมด และไปข้างหน้าและอ่านหนังสือทั้งหมด แต่คิดด้วยตัวคุณเอง

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

มีความคิดเห็นสองประเภทที่ควรพิจารณา - สิ่งเหล่านี้ปรากฏแก่ผู้ที่มีรหัสและผู้ที่ใช้ในการสร้างเอกสาร

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

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

ค่าของความคิดเห็นนั้นวัดจากมูลค่าของข้อมูลที่ให้ลบด้วยความพยายามที่จำเป็นในการอ่านและ / หรือเพิกเฉย ดังนั้นถ้าเราวิเคราะห์ความคิดเห็น

/// <summary>
/// Retrieves a product by its id, returns null if no product was found.
/// </summary>

สำหรับมูลค่าและต้นทุนเราเห็นสามสิ่ง:

1. Retrieves a product by its idทำซ้ำสิ่งที่ชื่อของฟังก์ชั่นพูดว่าดังนั้นจึงไม่มีค่า มันควรจะถูกลบ

2. returns null if no product was foundเป็นข้อมูลที่มีค่ามาก มันน่าจะช่วยลดเวลาที่ผู้ใช้โคเดอร์คนอื่น ๆ ฉันค่อนข้างแน่ใจว่ามันจะช่วยประหยัดการอ่านมากกว่าค่าใช้จ่ายในการอ่านที่แนะนำตัวเอง มันควรจะอยู่

3. เส้น

   /// <summary>
   /// </summary>
   

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

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

การสังเกตที่ฉันไม่ได้พบในคำตอบอื่น ๆ :

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

//XXX: The obvious way to do this would have been ...
//     However, since we need this functionality primarily for ...
//     doing this the non-obvious way of ...
//     gives us the advantage of ...

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

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

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

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

ในบางภาษา (เช่น F #) ความคิดเห็น / เอกสารทั้งหมดนี้สามารถแสดงในลายเซ็นวิธีการได้ นี่เป็นเพราะใน F # โดยทั่วไปแล้วโมฆะจะไม่ใช่ค่าที่อนุญาตเว้นแต่ได้รับอนุญาตเป็นการเฉพาะ

อะไรคือสิ่งที่พบได้บ่อยใน F # (และยังมีหลายภาษาการทำงานอื่น ๆ ) คือแทนที่จะ null คุณใช้ตัวเลือกประเภทOption<T>ซึ่งอาจเป็นได้ทั้งหรือNone Some(T)จากนั้นภาษาจะเข้าใจสิ่งนี้และบังคับให้คุณ (หรือเตือนคุณหากคุณไม่ตรงกัน) ในทั้งสองกรณีเมื่อคุณพยายามใช้

ตัวอย่างเช่นใน F # คุณอาจมีลายเซ็นที่มีลักษณะเช่นนี้

val GetProductById: int -> Option<Product>

แล้วนี่จะเป็นฟังก์ชั่นที่รับหนึ่งพารามิเตอร์ (int) จากนั้นส่งคืนผลิตภัณฑ์หรือไม่มีค่า

จากนั้นคุณสามารถใช้มันได้

let product = GetProduct 42
match product with
| None -> printfn "No product found!"
| Some p -> DoThingWithProduct p

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

แน่นอนสิ่งนี้ต้องการให้ภาษาของคุณได้รับการออกแบบในลักษณะนี้ - ซึ่งมีภาษาทั่วไปมากมายเช่น C #, Java, C ++ ฯลฯ ดังนั้นสิ่งนี้อาจไม่เป็นประโยชน์กับคุณในสถานการณ์ปัจจุบันของคุณ แต่ก็หวังว่าจะมีภาษาที่ช่วยให้คุณแสดงข้อมูลประเภทนี้ในลักษณะที่พิมพ์แบบคงที่โดยไม่ต้องใช้ความคิดเห็น ฯลฯ :)

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

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

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

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

ฉันมักจะรำคาญเมื่อเห็นความคิดเห็นเช่น "x = x + 7; // เพิ่ม 7 ถึง x" เช่นว้าวขอบคุณถ้าฉันลืมเครื่องหมายบวกหมายความว่าอาจมีประโยชน์มาก ที่ฉันอาจสับสนได้ในการรู้ว่า "x" คืออะไรหรือทำไมต้องเพิ่ม 7 ลงในเวลานี้ รหัสนี้อาจทำเป็นเอกสารด้วยตนเองโดยให้ชื่อที่มีความหมายมากกว่ากับ "x" และใช้ค่าคงที่เชิงสัญลักษณ์แทน 7 เช่นเดียวกับที่คุณเขียน "total_price = total_price + MEMBERSHIP_FEE;" ดังนั้นความคิดเห็นอาจไม่จำเป็นเลย .

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

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