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

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

12 comments  source-code 

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

12 php  comments 

ฉันกำลังทำงานในโครงการ "สปาเก็ตตี้โค้ด" และในขณะที่ฉันกำลังแก้ไขข้อบกพร่องและใช้งานคุณสมบัติใหม่ ๆ ฉันก็ทำการปรับโครงสร้างใหม่เพื่อให้สามารถทดสอบโค้ดหน่วยได้ รหัสมักจะถูกรวมเข้าด้วยกันอย่างแน่นหนาหรือซับซ้อนซึ่งการแก้ไขข้อบกพร่องเล็ก ๆ จะส่งผลให้มีการเขียนคลาสใหม่จำนวนมาก ดังนั้นฉันจึงตัดสินใจวาดเส้นหนึ่งในรหัสที่ฉันหยุด refactoring เพื่อให้ชัดเจนฉันวางความคิดเห็นในรหัสอธิบายสถานการณ์เช่น: class RefactoredClass { private SingletonClass xyz; // I know SingletonClass is a Singleton, so I would not need to pass it here. // However, I would like to get rid of it in the future, so it is passed …

11 refactoring  comments 

มีวิธีปฏิบัติทั่วไปในการแสดงความคิดเห็นนิพจน์ทั่วไปหรือไม่: ความคิดเห็นแบบอินไลน์อ้างอิงส่วนต่าง ๆ ของ RegEx หรือความคิดเห็นทั่วไปสำหรับการแสดงออกทั้งหมด?

11 documentation  coding-style  comments 

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

11 coding-style  team  comments 

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

11 java  code-quality  api  comments 

เมื่อฉันเขียนสคริปต์ขนาดเล็กสำหรับตัวเองฉันสแต็ครหัสของฉันสูงด้วยความคิดเห็น (บางครั้งฉันแสดงความคิดเห็นมากกว่าฉันรหัส) ผู้คนจำนวนมากที่ฉันพูดคุยเพื่อบอกว่าฉันควรจะบันทึกสคริปต์เหล่านี้แม้ว่าพวกเขาจะเป็นส่วนตัวดังนั้นถ้าฉันจะขายพวกเขาฉันจะพร้อม แต่ไม่ได้แสดงความคิดเห็นในรูปแบบของเอกสารใช่หรือไม่ จะไม่นี้: $foo = "bar"; # this is a comment print $foo; # this prints "bar" ได้รับการพิจารณาเอกสารโดยเฉพาะอย่างยิ่งหากนักพัฒนาซอฟต์แวร์กำลังใช้รหัสของฉันหรือไม่ หรือเอกสารประกอบนั้นถูกพิจารณาว่าอยู่นอกรหัสหรือไม่

11 documentation  comments 

ฉันเคยเป็นแฟนที่ต้องการแสดงความคิดเห็น XML สำหรับเอกสาร ฉันเปลี่ยนใจเนื่องจากเหตุผลหลักสองข้อ: เช่นเดียวกับรหัสที่ดีวิธีการควรอธิบายด้วยตนเอง ในทางปฏิบัติความคิดเห็น XML ส่วนใหญ่เป็นเสียงที่ไร้ประโยชน์ซึ่งไม่มีค่าเพิ่มเติม หลายครั้งที่เราใช้ GhostDoc เพื่อสร้างความคิดเห็นทั่วไปและนี่คือสิ่งที่ฉันหมายถึงด้วยเสียงไร้ประโยชน์: /// <summary> /// Gets or sets the unit of measure. /// </summary> /// <value> /// The unit of measure. /// </value> public string UnitOfMeasure { get; set; } สำหรับฉันนั่นชัดเจน ต้องบอกว่าถ้ามีคำแนะนำพิเศษที่จะรวมแล้วเราควรใช้ความเห็น XML อย่างแน่นอน ฉันชอบข้อความที่ตัดตอนมาจากบทความนี้ : บางครั้งคุณจะต้องเขียนความคิดเห็น แต่ควรเป็นข้อยกเว้นไม่ใช่กฎ ความคิดเห็นควรใช้เมื่อแสดงสิ่งที่ไม่สามารถแสดงในรหัสได้ หากคุณต้องการเขียนโค้ดที่หรูหราให้พยายามกำจัดความคิดเห็นและเขียนรหัสเอกสารเอง ฉันผิดที่คิดว่าเราควรใช้ความคิดเห็น …

10 .net  programming-practices  development-process  documentation  comments 

ฉันแสดงของรหัสเอกสารอย่างถูกต้องและผมตระหนักดีถึงข้อเสียเป็นไปได้ของมัน นั่นอยู่นอกขอบเขตของคำถามนี้ ฉันชอบที่จะปฏิบัติตามกฎของการเพิ่มความคิดเห็น XMLสำหรับสมาชิกสาธารณะทุกคนพิจารณาว่าฉันชอบ IntelliSense ใน Visual Studio มากแค่ไหน มีรูปแบบหนึ่งของความซ้ำซ้อนซึ่งแม้กระทั่งผู้วิจารณ์ที่มากเกินไปอย่างฉันก็ใส่ใจด้วย ตัวอย่างเช่นใช้List.Exists () /// <summary> /// Determines whether the List<T> contains elements /// that match the conditions defined by the specified predicate. /// </summary> /// <returns> /// true if the List<T> contains one or more elements that match the /// conditions …

10 documentation  comments  intellisense 

เป็นการดีหรือไม่ที่จะเขียนข้อคิดเห็นสำหรับวิธีที่รู้จักกันอย่างกว้างขวางเช่นเท่ากับ, เปรียบเทียบกับ ฯลฯ ? พิจารณารหัสด้านล่าง /** * This method compares the equality of the current object with the object of same type */ @Override public boolean equals(Object obj) { //code for equals } บริษัท ของฉันคลั่งไคล้ในการแสดงความคิดเห็นเช่นเดียวกับข้างต้นต้องใช้ความเห็น Javadoc ข้างต้นหรือไม่ มันไม่ชัดเจนและเข้าใจดีว่าวิธีการที่เท่าเทียมและชอบ (เปรียบเทียบ, เปรียบเทียบกับ) ฯลฯ ทำอย่างไร? คุณมีข้อเสนอแนะอะไร?

10 java  comments 

ฉันกำลังอ่านClean Codeของ Robert C. Martin และวลีนั้นTILTลึกลับปรากฏขึ้นในตัวอย่างโค้ดบางอย่าง ตัวอย่าง (ใน Java โดยวิธี): ... public String errorMessage() { switch (status) { case ErrorCode.OK: // TILT - Should not get here. return ""; case ErrorCode.UNEXPECTED_ARGUMENT: return "Unexpected argument"; case ErrorCode.MISSING_ARGUMENT: return "Missing argument"; ... } ... จากบริบทนี้ฉันเดาTILTว่าจะกำหนดสถานะที่ไม่สามารถเข้าถึงได้และรวมไว้เพียงเพื่อทำให้คอมไพเลอร์ (ตัวอย่างเช่นในโค้ดด้านบนTILTปรากฏในErrorCode.OKกรณีเนื่องจากไม่ควรมีข้อความแสดงข้อผิดพลาดหากรัฐเป็นOK) แต่ ฉันไม่แน่ใจ. ไม่มีใครรู้ว่าสิ่งที่TILTหมายถึง / หมายถึง?

9 java  clean-code  comments  conventions 

ฉันกำลังจะออกจากโครงการและก่อนที่เจ้านายของฉันจะขอให้ฉันทำเอกสารรหัส (ฉันยังไม่ได้บันทึกไว้เป็นอย่างดี) มันไม่ใช่เรื่องใหญ่โครงการไม่ซับซ้อนอย่างมาก แต่ฉันกำลังค้นหาสถานที่ในเอกสารของฉันที่ฉันอยากจะพูดว่า "แจ้งให้ทราบทางสาย XYZ ที่สิ่งนั้นเกิดขึ้นเช่นนั้น" ในกรณีนี้มันไม่เหมาะสมที่จะอ้างถึงหมายเลขบรรทัดที่ระบุเนื่องจากการเพิ่มหรือลบรหัสบรรทัดเดียวจะทำให้เอกสารในเอกสารล้าสมัยทันที มีวิธีปฏิบัติที่ดีที่สุดในการอ้างอิงบรรทัดรหัสเฉพาะโดยไม่อ้างอิงหมายเลขบรรทัดหรือไม่? ฉันได้พิจารณาทิ้งรหัสด้วยความคิดเห็นที่ชอบ: /* linetag 38FECD4F */ โดยที่ "38FECD4F" เป็นแท็กที่ไม่ซ้ำกันสำหรับบรรทัดนั้น จากนั้นฉันสามารถใส่เอกสาร "ในบรรทัดที่ติดแท็ก '38FECD4F' โปรดสังเกตว่าเกิดขึ้นเช่นนั้น" ความคิดอื่น ๆ ? ฉันรู้สึกเหมือนเป็นการดีกว่าที่จะจัดทำเอกสารรหัสหน่วยโดยรวมมากกว่าเฉพาะบางส่วนของพวกเขา แต่ในกรณีของโครงการนี้โดยเฉพาะมีการใช้รหัสขั้นตอนยาวซึ่งไม่เคยได้รับการปรับสภาพเป็นหน่วยเล็ก ๆ

9 documentation  comments 

ฉันต้องการเขียน Javadoc ด้วยวิธี DRY แต่เอกสาร oracle เกี่ยวกับJavadocกล่าวว่าเขียนสิ่งเดียวกันอีกครั้งในความคิดเห็นของเมธอด overload ฉันไม่สามารถหลีกเลี่ยงการทำซ้ำได้หรือไม่

9 documentation  comments  dry  javadocs 

ตามที่เป็นอยู่ในปัจจุบันคำถามนี้ไม่เหมาะสำหรับรูปแบบคำถาม & คำตอบของเรา เราคาดหวังคำตอบที่จะได้รับการสนับสนุนจากข้อเท็จจริงการอ้างอิงหรือความเชี่ยวชาญ แต่คำถามนี้อาจเรียกร้องให้มีการอภิปรายโต้แย้งโต้แย้งหรือการอภิปรายเพิ่มเติม หากคุณรู้สึกว่าคำถามนี้สามารถปรับปรุงและเปิดใหม่ได้โปรดไปที่ศูนย์ช่วยเหลือเพื่อขอคำแนะนำ ปิดให้บริการใน7 ปีที่ผ่านมา ฉันทำเช่นเดียวกัน เมื่อมีสิ่งที่ "ต้องทำ" //TODO ...ในรหัสของฉันฉันเขียน แต่ฉันอยากรู้ว่าจะเริ่มเมื่อไหร่และถ้ามีเหตุผลในการเขียน "to-dos" ในตัวพิมพ์ใหญ่ทั้งหมด?

9 comments 

นี่อาจเป็นคำถามที่โง่ แต่ก็อยู่ข้างหลังศีรษะของฉันซักพักแล้วและฉันไม่สามารถหาคำตอบที่เหมาะสมได้จากที่อื่น ฉันมีครูผู้หนึ่งที่บอกว่าเราควรระบุพารามิเตอร์แต่ละรายการด้วยคำอธิบายอย่างชัดเจนแม้ว่าจะมีเพียงพารามิเตอร์เดียวเท่านั้น สิ่งนี้นำไปสู่การซ้ำซ้อนมากมาย: double MyFunction(const int MyParam); // Function: MyFunction // Summary: Does stuff with MyParam. // Input: int MyParam - The number to do stuff with. // Output: MyParam with stuff done to it. เมื่อเขียนเอกสารในโค้ดคุณมีรายละเอียดมากน้อยเพียงใด?

9 documentation  comments  coding-style