คำถามติดแท็ก documentation

เหตุใดเอกสารในบางภาษาจึงพูดว่า "เทียบเท่า" แทนที่จะเป็น "?" ตัวอย่างเช่นPython Docsพูด itertools.chain(*iterables) ... เทียบเท่ากับ: def chain(*iterables): # chain('ABC', 'DEF') --> A B C D E F for it in iterables: for element in it: yield element หรือการอ้างอิง C ++บนfind_if: พฤติกรรมของแม่แบบฟังก์ชั่นนี้เทียบเท่ากับ: template<class InputIterator, class UnaryPredicate> InputIterator find_if (InputIterator first, InputIterator last, UnaryPredicate pred) { while (first!=last) …

23 c++  python  documentation  compiler 

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

22 documentation  code-reviews  documentation-generation  help-documentation 

ดูเหมือนว่าบิตของการขัดแย้งเรื่องทุกอย่างเอกสารรวมทั้ง "JavaBean" ไวยากรณ์ของ getters และ setters สำหรับเขตข้อมูล: คนบอกว่ามันไม่มีความจำเป็นที่ยาวนานและทำลายซ้ำแห้ง (ไม่ซ้ำตัวเอง) , ที่ประชุมตั้งชื่อควรจะอธิบายทุกอย่าง , และมันก็เป็นรหัส / เอกสาร บางครั้งข้อโต้แย้งเหล่านี้ทำงาน แต่ในบางครั้งคุณต้องจบเรื่องนี้: ข้างต้นเป็นเรื่องธรรมดาสำหรับโครงการโอเพ่นซอร์สที่ทำตามหลักการเหล่านั้นอย่างกล้าหาญ คุณเหลือเอกสารไร้ประโยชน์โดยสิ้นเชิง ที่ไม่ได้อธิบายอะไรเกี่ยวกับสิ่งที่เกิดขึ้นภายใต้ผลกระทบที่เป็นไปได้หรือแม้กระทั่งสิ่งที่คาดหวังมูลค่า (อาจเป็นโมฆะหรือไม่เคยโมฆะฉันไม่รู้ Javadoc ไม่บอกฉัน) ดังนั้นฉันควรเอกสารเมื่อใด ฉันทำเอกสารทุกอย่างแม้ว่าจะเป็นครั้งคราวรหัส clutters? หรือฉันไม่มีเอกสารอะไรตั้งแต่ในสายตาของฉันมัน "ชัดเจน"?

22 documentation 

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

22 unit-testing  documentation 

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

21 documentation  specifications  writing 

ความเป็นมา: ผู้ทำงานร่วมกันของฉันและฉันกำลังเขียนบทความสำหรับวารสารวิชาการ ในหลักสูตรการวิจัยของเราเราเขียนโปรแกรมจำลองใน Java เราต้องการให้โปรแกรมจำลองใช้ได้อย่างอิสระให้ผู้อื่นใช้ เราได้ตัดสินใจที่จะโฮสต์รหัสในที่เก็บ GitHub เพื่อให้ผู้อื่นใช้ง่ายขึ้นเราต้องการเขียนเอกสารที่ดีสำหรับโปรแกรมของเรารวมถึง: Javadocs สำหรับแต่ละชั้นเรียนและวิธีการ วิธีใช้รหัส อธิบายโครงสร้างระดับสูงของรหัส คำถามระดับสูงของฉันคือ: คุณสามารถให้ตัวอย่างที่ดีของคำและไดอะแกรมที่สามารถใช้อธิบายโครงสร้างระดับสูงของโปรแกรมได้หรือไม่? ซึ่งรวมถึงคำถามย่อย: เราจะแสดงคลาสที่มีอยู่ในแพ็คเกจใดได้อย่างไร เราจะแสดงสิ่งที่แพคเกจขึ้นอยู่กับแพคเกจอื่น ๆ ? เราจะแสดงให้เห็นว่าวัตถุ / คลาสในโปรแกรมทำงานร่วมกันได้อย่างไร เราพยายามใช้หลักการออกแบบที่เน้นการใช้โดเมนในการออกแบบรหัสของฉัน เราจะแสดงความสอดคล้องกันระหว่างวัตถุในโดเมนและไฟล์ซอร์สโค้ดเฉพาะที่เข้ารหัสวัตถุเหล่านี้ได้อย่างไร (ดูคำอธิบาย "ภาษาที่แพร่หลาย" ของโครงการด้านล่าง) สิ่งที่ฉันได้ทำไปแล้ว ภาษาที่แพร่หลาย เราใส่คำอธิบาย "ภาษาที่แพร่หลาย" ของรหัสลงในไฟล์ubiquitous-language.mdเนื้อหาด้านล่าง จุดประสงค์ของโครงการนี้คือการศึกษาว่านโยบายการเติมเต็มประสิทธิภาพในห่วงโซ่อุปทานแบบง่าย ๆ ด้วยศูนย์เดียวภายใต้ตัวเลือกระยะเวลาที่แตกต่างกันรายงานความล่าช้าและตัวแบบอุปสงค์ ในแต่ละช่วงเวลาเหตุการณ์ต่อไปนี้จะเกิดขึ้น: หากการจัดส่งมีกำหนดที่จะมาถึงโรงงานในช่วงเวลาปัจจุบันระดับสินค้าคงคลังของโรงงานจะเพิ่มขึ้นตามหน่วย X หากกำหนดการแสดงให้เห็นว่าในงวดปัจจุบันเป็นระยะเวลาที่รายงานจากนั้นสถานที่ยื่นรายงานไปยัง ผู้จัดจำหน่าย ซัพพลายเออร์ที่อาจได้รับรายงาน ทันทีหรือมีความล่าช้าหลายสัปดาห์ที่ผ่านมาตามที่ระบุโดยกำหนดการ หากซัพพลายเออร์ได้รับรายงานจากนั้นขึ้นอยู่กับ นโยบายการเติมเต็มมันจะคำนวณปริมาณการเติมเต็มของหน่วย X การจัดส่งหน่วย X ของผลิตภัณฑ์จะถูกกำหนดให้มาถึงหลังจากเวลานำของรอบระยะเวลา l ลูกค้ามาถึงโรงงานและต้องการหน่วย …

20 java  documentation 

ดังนั้นเราจึงมีส่วนต่อประสานเช่นนั้น /// <summary> /// Interface for classes capable of creating foos /// </summary> public interface ICreatesFoo { /// <summary> /// Creates foos /// </summary> void Create(Foo foo); /// <summary> /// Does Bar stuff /// </summary> void Bar(); } เมื่อเร็ว ๆ นี้เราได้เล่นเรื่องเอกสารที่เกี่ยวข้องกับการสร้างและตรวจสอบให้แน่ใจว่ามีเอกสาร XML มากมายดังกล่าวข้างต้น สิ่งนี้ทำให้เกิดเอกสารซ้ำซ้อนมากมาย ตัวอย่างการนำไปใช้: /// <summary> /// A Foo …

20 c#  documentation  xml  documentation-generation 

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

19 documentation  hiring  outsourcing  knowledge-transfer  wordpress 

บางครั้งถึงแม้ไม่บ่อยนักฉันก็ต้องรวมตรรกะคณิตศาสตร์ไว้ในรหัสด้วย แนวคิดที่ใช้ส่วนใหญ่จะง่ายมาก แต่โค้ดผลลัพธ์ไม่ใช่ - ตัวแปรจำนวนมากที่มีจุดประสงค์ที่ไม่ชัดเจนและการดำเนินการบางอย่างที่มีเจตนาไม่ชัดเจน ผมไม่ได้หมายความว่ารหัสไม่สามารถอ่านหรือ unmaintainable เพียงแค่ว่ามันเป็นwaaaayยากที่จะเข้าใจกว่าปัญหาทางคณิตศาสตร์ที่เกิดขึ้นจริง ฉันพยายามที่จะแสดงความคิดเห็นส่วนที่ยากที่สุดที่จะเข้าใจ แต่มีปัญหาเช่นเดียวกับในเวลาเพียงเข้ารหัสพวกเขา - ข้อความที่ไม่ได้มีการแสดงพลังของคณิตศาสตร์ ฉันกำลังมองหาวิธีที่มีประสิทธิภาพและเข้าใจได้ง่ายขึ้นในการอธิบายตรรกะที่อยู่เบื้องหลังโค้ดที่ซับซ้อนบางอย่างโดยเฉพาะอย่างยิ่งในโค้ดเอง ฉันถือว่า TeX - เขียนเอกสารและสร้างแยกต่างหากจากรหัส แต่ฉันต้องเรียนรู้ TeX และเอกสารจะไม่อยู่ในโค้ด อีกสิ่งหนึ่งที่ฉันคิดคือการถ่ายรูปสัญลักษณ์ทางคณิตศาสตร์สมการและไดอะแกรมที่เขียนบนกระดาษ / ไวท์บอร์ดและรวมไว้ใน javadoc มีวิธีที่ง่ายและชัดเจนกว่าหรือไม่? PS การให้ชื่อที่สื่อความหมาย ( timeOfFirstEventแทนt1) กับตัวแปรทำให้โค้ดมีความละเอียดมากขึ้นและอ่านได้ยากขึ้น

19 java  documentation  math 

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

18 java  documentation  refactoring  javadocs 

ปิด คำถามนี้เป็นคำถามความคิดเห็นตาม ไม่ยอมรับคำตอบในขณะนี้ ต้องการปรับปรุงคำถามนี้หรือไม่ อัปเดตคำถามเพื่อให้สามารถตอบข้อเท็จจริงและการอ้างอิงได้โดยแก้ไขโพสต์นี้ ปิดให้บริการใน5 ปีที่ผ่านมา ทุกคนรู้ว่าการพัฒนาซอฟต์แวร์ที่มีเอกสารที่ดีจะนำไปสู่ความสำเร็จ อย่างไรก็ตามมันมักจะหมายถึงว่าไม่เพียง แต่ข้อความธรรมดา แต่ยังรวมถึงเนื้อหาไบนารีที่จะมีส่วนร่วมในเอกสารเช่นแผนภาพ UML และฉันเคยได้ยินหลายคนพูดอย่างนั้น ระบบควบคุมเวอร์ชันไม่เหมาะสมสำหรับไฟล์ไบนารี ฉันเข้าใจและเห็นด้วยอย่างยิ่งกับปัญหา ฉันถามนักพัฒนาที่มีประสบการณ์หลายคนว่าควรเก็บเอกสารไว้ที่ไหนดีที่สุดและคำตอบที่ฉันได้รับคือ "วิกิ" Wiki ดี แต่ฉันคิดว่าเป็นปัญหาที่อาจเกิดขึ้นอีก ซอร์สโค้ดที่เก็บไว้ในระบบควบคุมเวอร์ชันสามารถเชื่อมต่อกับเอกสารที่เกี่ยวข้องในวิกิได้อย่างไร? สมมติว่ามีคนโคลนที่เก็บของคอมไพล์หรือ Mercurial เขา / เธอสามารถค้นหาเอกสารได้อย่างง่ายดายได้อย่างไร? หรือฉันเพิ่งจะพลาดอะไรไป? ฉันรู้ว่าระบบวิกิบางระบบมีความสามารถในการรวมเข้ากับระบบควบคุมแหล่งที่มา แต่ข้อกังวลของฉันไม่ได้เกี่ยวกับความสามารถในการรวมเข้าด้วยกัน หากคุณได้โคลนซอร์สโค้ดจากที่เก็บคอมไพล์และหลังจากนั้นไม่นานคุณก็ขึ้นรถไฟและต้องการทำงานออฟไลน์บนรถไฟต่อไป (ซึ่งเป็นคุณสมบัติที่สำคัญของ DVCS) ทันใดนั้นคุณก็รู้ว่าคุณไม่สามารถเข้าถึงเอกสารใด ๆ ได้เนื่องจากคุณทำงานออฟไลน์บนรถไฟ ในทางตรงกันข้ามถ้าเอกสารถูกเก็บไว้ในที่เก็บ git คุณจะสามารถเข้าถึงเอกสารที่มีการโคลนที่เก็บ

18 documentation  wiki 

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

18 documentation  knowledge-transfer 

ฉันได้รับการมองเข้าไปในวิธีการเอกสารโครงการซอฟต์แวร์มากขึ้นอย่างเป็นทางการและฉันได้เรียนรู้เกี่ยวกับมาตรฐาน IEEE 830-1998: การปฏิบัติที่แนะนำสำหรับการซอฟต์แวร์ข้อกำหนดจำเพาะ อย่างไรก็ตามอย่างที่คุณเห็นจากลิงค์นั้นมันถูกแทนที่ ฉันรู้ว่า 830-1998 และอาจเป็น 830-1993 อาจจะใช้ได้ดี อย่างไรก็ตามถ้าไม่มีอะไรอื่นฉันอยากจะรู้ว่ามาตรฐานได้แทนที่มัน ในกรณีนี้มันอาจจะไม่สำคัญ แต่ถ้ามาตรฐานอื่นถูกแทนที่สำหรับสิ่งทางเทคนิคเพิ่มเติมฉันคิดว่ามันเป็นความคิดที่ดีที่จะเชื่อมโยงบางสิ่งที่มาตรฐานแทนที่อื่น (ถ้าไม่ใช่อีกอันในบรรทัดเดียวกัน (830 ในนี้ กรณี)). เป็นมูลค่าการกล่าวขวัญว่า: มาตรฐานล่าสุดเมื่อค้นหา "ข้อกำหนดข้อกำหนดซอฟต์แวร์" หรือ "ข้อกำหนดซอฟต์แวร์" บนเว็บไซต์สมาคมมาตรฐาน IEEE คือ 830-1993 SWEBOKรุ่น 2004 (ปัจจุบัน) อ้างอิง 830-1993 ( ย่อหน้า 2.5 ) บทความ Wikipediaของเอกสารไม่ได้ระบุว่ามาตรฐานถูกแทนที่ TLDR: คุณจะพบสิ่งที่มาตรฐานแทนที่อื่นและสิ่งหนึ่งที่เกิดขึ้น 830-1998 ได้อย่างไร

17 documentation  requirements  standards 

เราทุกคนได้เห็นตัวอย่างมากมายของซอฟต์แวร์ที่มาพร้อมกับ "ความต้องการขั้นต่ำของระบบ" ดังต่อไปนี้: Windows XP / Vista / 7 RAM 1GB พื้นที่เก็บข้อมูล 200 MB โดยทั่วไปแล้วจะมีวิธีพิจารณาอย่างไร เห็นได้ชัดว่าบางครั้งมีข้อ จำกัด เฉพาะ (ถ้าโปรแกรมใช้พื้นที่ 200 MB บนดิสก์นั่นเป็นข้อกำหนดที่ยากมาก) นอกเหนือจากสถานการณ์เหล่านั้นหลาย ๆ ครั้งสำหรับสิ่งต่าง ๆ เช่น RAM หรือตัวประมวลผลปรากฎว่ามากขึ้น / เร็วขึ้นดีขึ้นโดยไม่มีข้อ จำกัด อย่างหนัก สิ่งเหล่านี้ถูกกำหนดอย่างไร? นักพัฒนาทำตัวเลขที่ดูเหมือนสมเหตุสมผลหรือไม่ QA ผ่านกระบวนการที่เข้มงวดเพื่อทดสอบข้อกำหนดต่างๆจนกว่าพวกเขาจะพบการตั้งค่าต่ำสุดพร้อมประสิทธิภาพที่ยอมรับได้หรือไม่? สัญชาตญาณของฉันบอกว่ามันควรจะเป็นหลัง แต่มักจะเป็นอดีตในทางปฏิบัติ

17 documentation  requirements  qa 

หนึ่งในทีมของฉันเชื่อว่าจำเป็นต้องเขียนความคิดเห็น javadoc สำหรับพารามิเตอร์ EVERY ในลายเซ็นของเมธอด ฉันไม่คิดว่ามันเป็นสิ่งจำเป็นและอันที่จริงฉันคิดว่ามันอาจเป็นอันตรายได้ ก่อนอื่นฉันคิดว่าชื่อพารามิเตอร์ควรเป็นคำอธิบายและจัดทำเอกสารด้วยตนเอง หากไม่ชัดเจนว่าพารามิเตอร์ของคุณเป็นอย่างไรคุณอาจทำผิด อย่างไรก็ตามฉันเข้าใจว่าบางครั้งมันก็ไม่ชัดเจนว่าพารามิเตอร์สำหรับดังนั้นในกรณีเหล่านั้นใช่คุณควรเขียนความคิดเห็น javadoc อธิบายพารามิเตอร์ แต่ฉันคิดว่ามันไม่จำเป็นที่จะทำเช่นนั้นสำหรับพารามิเตอร์ทุกคน หากเห็นได้ชัดว่าพารามิเตอร์สำหรับความคิดเห็น javadoc นั้นซ้ำซ้อน; คุณกำลังสร้างงานพิเศษสำหรับตัวคุณเอง นอกจากนี้คุณกำลังสร้างงานพิเศษสำหรับทุกคนที่ต้องรักษารหัสของคุณ วิธีการเปลี่ยนแปลงเมื่อเวลาผ่านไปและการบำรุงรักษาความคิดเห็นเกือบจะสำคัญเท่ากับการบำรุงรักษาโค้ดของคุณ มีกี่ครั้งที่คุณเห็นความคิดเห็นเช่น "X ทำ Y เพื่อ Z เหตุผล" เพียงเพื่อดูว่าความคิดเห็นนั้นล้าสมัยและในความเป็นจริงวิธีการไม่ได้ใช้พารามิเตอร์ X อีกต่อไป? มันเกิดขึ้นตลอดเวลาเพราะคนลืมที่จะอัพเดทความคิดเห็น ฉันจะยืนยันว่าความคิดเห็นที่ทำให้เข้าใจผิดเป็นอันตรายมากกว่าความคิดเห็นที่ไม่ทั้งหมด และดังนั้นจึงเป็นอันตรายของการแสดงความคิดเห็นมากเกินไป: โดยการสร้างเอกสารที่ไม่จำเป็นคุณจะต้อง อย่างไรก็ตามฉันเคารพนักพัฒนาคนอื่นในทีมของฉันและยอมรับว่าบางทีเขาอาจจะพูดถูกและฉันผิด ทำไมฉันถึงนำคำถามมาให้คุณผู้พัฒนาเพื่อน: จำเป็นต้องเขียนความคิดเห็น javadoc สำหรับพารามิเตอร์ EVERY หรือไม่? สมมติว่านี่เป็นรหัสภายใน บริษัท ของฉันและบุคคลภายนอกใด ๆ จะไม่ถูกใช้

17 java  documentation  source-code  comments  maintainability