docblock เป็นประเภทคำแนะนำซ้ำซ้อนเมื่อใช้การพิมพ์ที่เข้มงวด

ฉันมี codebase ส่วนตัวขนาดใหญ่มากซึ่งมีการพัฒนามาประมาณสิบปีแล้ว ฉันไม่ได้ใช้ phpDocumentor แต่เนื่องจากการใช้ส่วน docblock ได้กลายเป็นมาตรฐานในโครงการโอเพ่นซอร์สฉันได้ใช้การเขียน docblock สำหรับวิธีสาธารณะทั้งหมดในที่เก็บของฉันเช่นกัน บล็อกส่วนใหญ่มีเพียงคำอธิบายขนาดเล็กและคำแนะนำสำหรับพารามิเตอร์ทั้งหมดและประเภทผลตอบแทน

ด้วยการมาถึงของการวิเคราะห์แบบคงที่คำใบ้ประเภทนี้ช่วยให้ฉันค้นหาความไม่สอดคล้องและข้อบกพร่องที่อาจเกิดขึ้นได้มากมาย เมื่อเร็ว ๆ นี้ฉันได้แปลง codebase ทั้งหมด (ตอนนี้ทำงานบน PHP7.2) เพื่อให้พารามิเตอร์ทั้งหมดและส่งคืนค่าชนิดที่บอกใบ้เท่าที่จะเป็นไปได้โดยใช้ typehints ของ PHP และตอนนี้ฉันสงสัยว่า ... docblock typehints redundant เหล่านี้ไม่ใช่หรือ มันขอให้ทำงานค่อนข้างน้อยเพื่อให้ docblock ทั้งหมดสอดคล้องกับรหัสที่เปลี่ยนแปลงตลอดเวลาและเนื่องจากพวกเขาไม่ได้เพิ่มข้อมูลใหม่ฉันสงสัยว่ามันเป็นการดีที่จะลบออกทั้งหมดหรือไม่

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

ข้อมูลที่สามารถพบได้ในรหัสไม่ควรทำซ้ำในความคิดเห็น

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

หากคุณดู DocBlock ที่เทียบเท่ากับภาษาที่พิมพ์แบบคงที่ (เช่น Java, C #) คุณจะพบว่าความคิดเห็นของ doc ไม่มีข้อมูลประเภท ตราบเท่าที่เป็นกรณีนี้ในรหัส PHP ของคุณฉันขอแนะนำให้ทำตามเหมาะสม แน่นอนว่าไม่สามารถใช้การแนะนำประเภทได้ความคิดเห็นยังคงเป็นทางเลือกที่ดีที่สุดของคุณ

สิ่งนี้ไม่เกี่ยวข้องกับ PHP แต่ข้อมูลประเภทที่ซ้ำกันจะสมเหตุสมผลเมื่อประเภทถูกอนุมานโดยนัย (เช่น Haskell)

ใช่ docblocks กลายเป็น redundant ด้วย php 7

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

ฉันไม่ได้เขียน docblocks อีกต่อไปยกเว้นเมื่อฉันต้องการพิมพ์คำใบ้อาเรย์ของบางประเภท (เช่น@return int[]หรือ@param SomeStatus[] $statusList) หรือเมื่อฉันต้องการเพิ่มความคิดเห็นเกี่ยวกับวิธีการพารามิเตอร์หรือค่าส่งคืน ฉันพบว่ามันสำคัญที่จะต้องปิดการใช้งานการตรวจสอบ phpstorm ที่ก่อให้เกิดเมื่อคุณไม่มีพารามิเตอร์ที่ระบุและส่งคืนชนิดใน docblock หากคุณมี docblock

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

ในบางระบบไม่จำเป็นต้องระบุประเภทพารามิเตอร์ในเอกสารเนื่องจากสามารถนำมาจากรหัสได้ PHPDoc ไม่ใช่ระบบดังกล่าว แต่@paramแท็กจะได้รับการบันทึกไว้ว่า

เมื่อระบุแล้วจะต้องมีประเภทเพื่อระบุสิ่งที่คาดหวัง

“ การทำงานค่อนข้างน้อยเพื่อให้ docblock ทั้งหมดสอดคล้องกับรหัสที่เปลี่ยนแปลงตลอดเวลา” จะลดลงบ้างเนื่องจาก PHPDoc จะตรวจสอบคำแนะนำประเภทเอกสารกับคำแนะนำประเภทรหัส นี่คือการวิเคราะห์เชิงวิเคราะห์ / แบบคงที่ดังนั้นให้การสร้างเอกสารของคุณเป็นส่วนหนึ่งของระบบทดสอบอัตโนมัติของคุณ

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