แนวทางปฏิบัติที่ดีที่สุดในการเขียนความคิดเห็นและเอกสาร

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

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

โดยเฉพาะฉันสนใจ Java / Clojure / Python ที่นี่ แต่คำตอบไม่จำเป็นต้องเฉพาะภาษา

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

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

• ชื่อ / เอกสารควรบอกคุณว่าคุณกำลังทำอะไรอยู่

• การใช้งานควรบอกคุณว่าคุณกำลังทำอะไรอยู่

• ความคิดเห็นควรบอกคุณว่าทำไมคุณถึงทำแบบที่คุณทำ

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

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

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

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

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

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

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

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

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

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

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

และที่สำคัญยิ่งกว่า: มี "นโยบายการแสดงความคิดเห็น" หรือกลยุทธ์ที่ยอมรับได้หรือไม่? มีคำแนะนำมากมายเกี่ยวกับวิธีการตั้งรหัส --- แต่เกี่ยวกับ "วิธีการแสดงความคิดเห็น"

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

เฉพาะแหล่งจาวาหนึ่งเดียวที่ฉันชอบคือวิธีเขียนความเห็นเอกสารสำหรับเครื่องมือ Javadocของ Oracle :

เอกสารนี้อธิบายถึงแนวทางแบบแผนแท็กและข้อกำหนดเกี่ยวกับรูปภาพที่เราใช้ในความคิดเห็นเอกสารประกอบสำหรับโปรแกรม Java ที่เขียนที่ Java Software, Sun Microsystems

และรายการที่ 44: เขียนความคิดเห็นเอกสารสำหรับองค์ประกอบ API ที่เปิดเผยทั้งหมด :

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

จากการที่มีประสิทธิภาพ Java ฉบับที่