Modifying Existing Code (การแก้ไขโค้ดที่มีอยู่)

Chapter 1 described how software development is iterative and incremental. บทที่ 1 ได้อธิบายว่าการพัฒนาซอฟต์แวร์เป็นกระบวนการวนซ้ำและเพิ่มเติมขั้นต่อขั้น A large software system develops through a series of evolutionary stages, where each stage adds new capabilities and modifies existing modules. ระบบซอฟต์แวร์ขนาดใหญ่พัฒนาผ่านชุดของขั้นตอนวิวัฒนาการ โดยแต่ละขั้นตอนเพิ่มความสามารถใหม่และแก้ไขหน่วยโค้ดที่มีอยู่ This means that a system's design is constantly evolving. นี่หมายความว่าการออกแบบระบบอยู่ในการวิวัฒนาการอย่างต่อเนื่อง It isn't possible to conceive the right design for a system at the outset; the design of a mature system is determined more by changes made during the system's evolution than by any initial conception. ไม่สามารถคิดออกแบบที่ถูกต้องสำหรับระบบตั้งแต่แรกเริ่มได้ การออกแบบของระบบที่เก่าแก่นั้นถูกกำหนดมากขึ้นจากการเปลี่ยนแปลงที่ทำระหว่างวิวัฒนาการของระบบมากกว่าการออกแบบเบื้องต้นใด ๆ Previous chapters described how to squeeze out complexity during the initial design and implementation; this chapter discusses how to keep complexity from creeping in as the system evolves. บทก่อนหน้านี้ได้อธิบายว่าจะกำจัดความซับซ้อนออกมาระหว่างการออกแบบเบื้องต้นและการนำไปใช้อย่างไร บทนี้กล่าวถึงวิธีการป้องกันไม่ให้ความซับซ้อนเข้ามาแทรกตัวเมื่อระบบวิวัฒนาการ

16.1 Stay strategic (คงอยู่ในกลยุทธ์)

Chapter 3 introduced the distinction between tactical programming and strategic programming: in tactical programming, the primary goal is to get something working quickly, even if that results in additional complexity; in strategic programming, the most important goal is to produce a great system design. บทที่ 3 ได้แนะนำความแตกต่างระหว่าง tactical programming และ strategic programming: ใน tactical programming เป้าหมายหลักคือการทำให้บางสิ่งทำงานได้อย่างรวดเร็ว แม้ว่าจะทำให้เกิดความซับซ้อนเพิ่มเติมก็ตาม ใน strategic programming เป้าหมายที่สำคัญที่สุดคือการสร้างการออกแบบระบบที่ยอดเยี่ยม The tactical approach very quickly leads to a messy system design. วิธี tactical approach นำไปสู่การออกแบบระบบที่ยุ่งเหยิงอย่างรวดเร็ว If you want to have a system that is easy to maintain and enhance, then "working" isn't a high enough standard; you have to prioritize design and think strategically. หากคุณต้องการให้ระบบสามารถบำรุงรักษาและพัฒนาได้ง่าย "ทำงาน" ก็ไม่ใช่มาตรฐานที่สูงพอ คุณต้องสำคัญการออกแบบและคิดแบบกลยุทธ์ This idea also applies when you are modifying existing code. แนวคิดนี้ยังใช้ได้เมื่อคุณแก้ไขโค้ดที่มีอยู่

Unfortunately, when developers go into existing code to make changes such as bug fixes or new features, they don't usually think strategically. น่าเสียดายที่เมื่อนักพัฒนาเข้าไปแก้ไขโค้ดที่มีอยู่เพื่อทำการเปลี่ยนแปลงเช่นการแก้ไขจุดบกพร่องหรือฟีเจอร์ใหม่ พวกเขามักจะไม่คิดแบบกลยุทธ์ A typical mindset is "what is the smallest possible change I can make that does what I need?" จิตสำนึกทั่วไปคือ "การเปลี่ยนแปลงที่เล็กที่สุดที่ผมสามารถทำได้คืออะไรที่ทำตามที่ผมต้องการ?" Sometimes developers justify this because they are not comfortable with the code being modified; they worry that larger changes carry a greater risk of introducing new bugs. บางครั้งนักพัฒนากลับความเห็นนี้เพราะพวกเขาไม่สบายใจกับโค้ดที่ถูกแก้ไข พวกเขากังวลว่าการเปลี่ยนแปลงที่ใหญ่ขึ้นมีความเสี่ยงที่สูงขึ้นในการแนะนำจุดบกพร่องใหม่ However, this results in tactical programming. อย่างไรก็ตาม นี่นำไปสู่ tactical programming Each one of these minimal changes introduces a few special cases, dependencies, or other forms of complexity. การเปลี่ยนแปลงที่น้อยที่สุดแต่ละรายการแนะนำกรณีพิเศษบางกรณี dependencies หรือรูปแบบความซับซ้อนอื่น ๆ As a result, the system design gets just a bit worse, and the problems accumulate with each step in the system's evolution. เป็นผลให้การออกแบบระบบแย่ลงเล็กน้อย และปัญหาสะสมตัวกับแต่ละขั้นตอนในวิวัฒนาการของระบบ

If you want to maintain a clean design for a system, you must take a strategic approach when modifying existing code. หากคุณต้องการรักษาการออกแบบที่สะอาดสำหรับระบบ คุณต้องใช้วิธี strategic approach เมื่อแก้ไขโค้ดที่มีอยู่ Ideally, when you have finished with each change, the system will have the structure it would have had if you had designed it from the start with that change in mind. ในอุดมคติ เมื่อคุณเสร็จสิ้นการเปลี่ยนแปลงแต่ละรายการ ระบบจะมีโครงสร้างที่มันจะมีถ้าคุณออกแบบมันตั้งแต่เริ่มต้นโดยคำนึงถึงการเปลี่ยนแปลงนั้น To achieve this goal, you must resist the temptation to make a quick fix. เพื่อให้บรรลุเป้าหมายนี้ คุณต้องต้านทานการล่อแหลมที่จะแก้ไขอย่างรวดเร็ว Instead, think about whether the current system design is still the best one, in light of the desired change. แต่อย่างไรก็ตาม ให้คิดว่าการออกแบบระบบปัจจุบันยังคงเป็นการออกแบบที่ดีที่สุดหรือไม่เมื่อพิจารณาจากการเปลี่ยนแปลงที่ต้องการ If not, refactor the system so that you end up with the best possible design. ถ้าไม่ใช่ ให้ refactor ระบบเพื่อให้คุณลงเอยด้วยการออกแบบที่ดีที่สุดที่เป็นไปได้ With this approach, the system design improves with every modification. ด้วยวิธี approach นี้ การออกแบบระบบจะปรับปรุงตัวเองด้วยการแก้ไขทุกครั้ง

This is also an example of the investment mindset introduced on page 15: if you invest a little extra time to refactor and improve the system design, you'll end up with a cleaner system. นี่ยังเป็นตัวอย่างของจิตสำนึกด้านการลงทุนที่แนะนำในหน้า 15: หากคุณลงทุนเพิ่มเติมเล็กน้อยเพื่อ refactor และปรับปรุงการออกแบบระบบ คุณจะลงเอยด้วยระบบที่สะอาดกว่า This will speed up development, and you will recoup the effort that you invested in the refactoring. นี่จะช่วยเพิ่มความเร็วในการพัฒนา และคุณจะได้รับคืนความพยายามที่คุณลงทุนไปใน refactoring Even if your particular change doesn't require refactoring, you should still be on the lookout for design imperfections that you can fix while you're in the code. แม้ว่าการเปลี่ยนแปลงเฉพาะของคุณไม่ต้องการ refactoring คุณควรระวังข้อบกพร่องในการออกแบบที่คุณสามารถแก้ไขได้ขณะที่คุณอยู่ในโค้ด Whenever you modify any code, try to find a way to improve the system design at least a little bit in the process. เมื่อใดก็ตามที่คุณแก้ไขโค้ด ให้พยายามค้นหาวิธีปรับปรุงการออกแบบระบบอย่างน้อยเล็กน้อยในกระบวนการ If you're not making the design better, you are probably making it worse. หากคุณไม่ทำให้การออกแบบดีขึ้น คุณอาจทำให้แย่ลงไป

As discussed in Chapter 3, an investment mindset sometimes conflicts with the realities of commercial software development. ดังที่กล่าวถึงใน บทที่ 3 จิตสำนึกด้านการลงทุนบางครั้งขัดแย้งกับความเป็นจริงของการพัฒนาซอฟต์แวร์เชิงพาณิชย์ If refactoring the system "the right way" would take three months but a quick and dirty fix would take only two hours, you may have to take the quick and dirty approach, particularly if you are working against a tight deadline. หาก refactor ระบบ "วิธีที่ถูกต้อง" จะใช้เวลาสามเดือน แต่การแก้ไขอย่างรวดเร็วและสกปรกจะใช้เวลาเพียงสองชั่วโมง คุณอาจต้องใช้วิธี quick and dirty approach โดยเฉพาะอย่างยิ่งหากคุณทำงานภายใต้ deadline ที่แคบ Or, if refactoring the system would create incompatibilities that affect many other people and teams, then the refactoring may not be practical. หรือ หากการ refactor ระบบจะสร้าง incompatibilities ที่ส่งผลต่อหลายคนและทีมอื่น ๆ การ refactor อาจไม่ใช่เรื่องจริง

Nonetheless, you should resist these compromises as much as possible. อย่างไรก็ตาม คุณควรต้านทานการประนีประนวมเหล่านี้มากที่สุดเท่าที่เป็นไปได้ Ask yourself "Is this the best I can possibly do to create a clean system design, given my current constraints?" ถามตัวเอง "นี่เป็นสิ่งที่ดีที่สุดที่ผมสามารถทำได้เพื่อสร้างการออกแบบระบบที่สะอาด โดยพิจารณาจากข้อจำกัดปัจจุบันของผม?" Perhaps there's an alternative approach that would be almost as clean as the 3-month refactoring but could be done in a couple of days? บางทีอาจมีวิธี approach อื่นที่จะสะอาดเกือบเท่ากับการ refactor 3 เดือน แต่สามารถทำได้ในไม่กี่วัน? Or, if you can't afford to do a large refactoring now, get your boss to allocate time for you to come back to it after the current deadline. หรือ หากคุณไม่สามารถทำ refactor ขนาดใหญ่ได้ตอนนี้ ให้บอสของคุณจัดสรรเวลาให้คุณกลับมาแก้ไขหลังจาก deadline ปัจจุบัน Every development organization should plan to spend a small fraction of its total effort on cleanup and refactoring; this work will pay for itself over the long run. องค์กรพัฒนาซอฟต์แวร์ทุกแห่งควรวางแผนใช้เศษส่วนเล็กน้อยของความพยายามทั้งหมดไปสำหรับ cleanup และ refactoring งานนี้จะจ่ายให้กับตัวเองในระยะยาว

16.2 Maintaining comments: keep the comments near the code (รักษาความเห็น: เก็บความเห็นไว้ใกล้กับโค้ด)

When you change existing code, there's a good chance that the changes will invalidate some of the existing comments. เมื่อคุณเปลี่ยนแปลงโค้ดที่มีอยู่ มีโอกาสที่ดีว่าการเปลี่ยนแปลงจะทำให้ความเห็นที่มีอยู่บางส่วนไม่ใช้ได้อีกต่อไป It's easy to forget to update comments when you modify code, which results in comments that are no longer accurate. เป็นเรื่องง่ายที่จะลืมอัปเดตความเห็นเมื่อคุณแก้ไขโค้ด ซึ่งนำไปสู่ความเห็นที่ไม่ถูกต้องอีกต่อไป Inaccurate comments are frustrating to readers, and if there are very many of them, readers begin to distrust all of the comments. ความเห็นที่ไม่ถูกต้องทำให้ผู้อ่านหงุดหงิด และหากมีมากมาย ผู้อ่านจะเริ่มไม่ไว้ใจความเห็นทั้งหมด Fortunately, with a little discipline and a couple of guiding rules, it's possible to keep comments up-to-date without a huge effort. โชคดีที่ด้วยวินัยเล็กน้อยและกฎแนวทางสองสามข้อ เป็นไปได้ที่จะให้ความเห็นทันสมัยโดยไม่ต้องใช้ความพยายามมากนัก This section and the following ones put forth some specific techniques. ส่วนนี้และส่วนต่อไปนี้นำเสนอเทคนิคเฉพาะบางประการ

The best way to ensure that comments get updated is to position them close to the code they describe, so developers will see them when they change the code. วิธีที่ดีที่สุดในการให้แน่ใจว่าความเห็นได้รับการอัปเดตคือการวางตำแหน่งไว้ใกล้กับโค้ดที่พวกเขาอธิบาย เพื่อให้นักพัฒนาเห็นพวกเขาเมื่อพวกเขาเปลี่ยนแปลงโค้ด The farther a comment is from its associated code, the less likely it is that it will be updated properly. ความเห็นยิ่งห่างไกลจากโค้ดที่เกี่ยวข้องมากเท่าไร ความเป็นไปได้ที่จะได้รับการอัปเดตอย่างถูกต้องก็จะลดลง For example, the best place for a method's interface comment is in the code file, right next to the body of the method. ตัวอย่างเช่น ที่ที่ดีที่สุดสำหรับ interface comment ของ method คือในไฟล์โค้ด ตรงถัดจากเนื้อหาของ method Any changes to the method will involve this code, so the developer is likely to see the interface comments and update them if needed. การเปลี่ยนแปลงใด ๆ ต่อ method จะเกี่ยวข้องกับโค้ดนี้ ดังนั้นนักพัฒนาจึงมีแนวโน้มที่จะเห็น interface comments และอัปเดตหากจำเป็น

An alternative for languages like C and C++ that have separate code and header files, is to place the interface comments next to the method's declaration in the .h file. ทางเลือกสำหรับภาษาเช่น C และ C++ ที่มีไฟล์โค้ดและ header แยกกัน คือการวาง interface comments ถัดจากการประกาศ method ในไฟล์ .h However, this is a long way from the code; developers won't see those comments when modifying the method's body, and it takes additional work to open a different file and find the interface comments to update them. อย่างไรก็ตาม นี่อยู่ห่างไกลจากโค้ด นักพัฒนาจะไม่เห็นความเห็นเหล่านั้นเมื่อแก้ไขเนื้อหาของ method และต้องใช้เวลาเพิ่มเติมในการเปิดไฟล์อื่นและค้นหา interface comments เพื่ออัปเดต Some might argue that interface comments should go in header files so that users can learn how to use an abstraction without having to look at the code file. บางคนอาจโต้แย้งว่า interface comments ควรจะอยู่ในไฟล์ header เพื่อให้ผู้ใช้สามารถเรียนรู้วิธีการใช้ abstraction โดยไม่ต้องดูไฟล์โค้ด However, users should not need to read either code or header files; they should get their information from documentation compiled by tools such as Doxygen or Javadoc. อย่างไรก็ตาม ผู้ใช้ไม่ควรต้องอ่านโค้ดหรือไฟล์ header พวกเขาควรได้รับข้อมูลจากเอกสารที่รวบรวมโดยเครื่องมือเช่น Doxygen หรือ Javadoc In addition, many IDEs will extract and present documentation to users, such as by displaying a method's documentation when the method's name is typed. นอกจากนี้ IDE หลายตัวจะแยกและนำเสนอเอกสารให้ผู้ใช้ เช่น โดยแสดง documentation ของ method เมื่อพิมพ์ชื่อ method Given tools such as these, the documentation should be located in the place that is most convenient for developers working on the code. ด้วยเครื่องมือเช่นนี้ เอกสารควรจะตั้งอยู่ในสถานที่ที่สะดวกที่สุดสำหรับนักพัฒนาที่ทำงานกับโค้ด

When writing implementation comments, don't put all the comments for an entire method at the top of the method. เมื่อเขียน implementation comments อย่าใส่ความเห็นทั้งหมดสำหรับ method ทั้งหมดไว้ที่ด้านบนของ method Spread them out, pushing each comment down to the narrowest scope that includes all of the code referred to by the comment. กระจายออกไป ดันความเห็นแต่ละรายการลงไปยังขอบเขตที่แคบที่สุดซึ่งรวมโค้ดทั้งหมดที่อ้างอิงถึงโดยความเห็น For example, if a method has three major phases, don't write one comment at the top of the method that describes all of the phases in detail. ตัวอย่างเช่น หากวิธี method มีสามขั้นตอนหลัก อย่าเขียนความเห็นเดียวที่ด้านบนของ method ที่อธิบายขั้นตอนทั้งหมดโดยละเอียด Instead, write a separate comment for each phase and position that comment just above the first line of code in that phase. แต่อย่างไรก็ตาม เขียนความเห็นแยกต่างหากสำหรับแต่ละเฟส และวางความเห็นนั้นไว้เหนือบรรทัดแรกของโค้ดในเฟสนั้น On the other hand, it can also be helpful to have a comment at the top of a method's implementation that describes the overall strategy, like this: ในทางกลับกัน อาจเป็นประโยชน์ที่จะมีความเห็นที่ด้านบนของ implementation ของ method ที่อธิบายกลยุทธ์ภาพรวม เช่นนี้:

//  We proceed in three phases:
//  Phase 1: Find feasible candidates
//  Phase 2: Assign each candidate a score
//  Phase 3: Choose the best, and remove it

Additional details can be documented just above the code for each phase. รายละเอียดเพิ่มเติมสามารถ documented ไว้ได้เหนือโค้ดสำหรับแต่ละเฟส

In general, the farther a comment is from the code it describes, the more abstract it should be (this reduces the likelihood that the comment will be invalidated by code changes). โดยทั่วไป ความเห็นยิ่งห่างไกลจากโค้ดที่มันอธิบายมากเท่าไร มันก็ควรจะเป็นนามธรรมมากขึ้นเท่านั้น (นี่จะลดโอกาสที่ความเห็นจะถูกทำให้ไม่ถูกต้องโดยการเปลี่ยนแปลงโค้ด)

16.3 Comments belong in the code, not the commit log (ความเห็นอยู่ในโค้ด ไม่ใช่ commit log)

A common mistake when modifying code is to put detailed information about the change in the commit message for the source code repository, but then not to document it in the code. ความผิดพลาดทั่วไปเมื่อแก้ไขโค้ดคือการใส่ข้อมูลโดยละเอียดเกี่ยวกับการเปลี่ยนแปลงใน commit message สำหรับ repository โค้ดต้นทาง แต่จากนั้นก็ไม่ได้ document ไว้ในโค้ด Although commit messages can be browsed in the future by scanning the repository's log, a developer who needs the information is unlikely to think of scanning the repository log. แม้ว่า commit messages สามารถเรียกดูได้ในอนาคตโดยการสแกน log ของ repository แต่นักพัฒนาที่ต้องการข้อมูลนั้นไม่น่าจะคิดถึงการสแกน repository log Even if they do scan the log, it will be tedious to find the right log message. แม้ว่าพวกเขาจะสแกน log แต่ก็จะเหนื่อยที่จะหา log message ที่ถูกต้อง

When writing a commit message, ask yourself whether developers will need to use that information in the future. เมื่อเขียน commit message ถามตัวเองว่านักพัฒนาจะต้องใช้ข้อมูลนั้นในอนาคตหรือไม่ If so, then document this information in the code. ถ้าเป็นเช่นนั้น ให้ document ข้อมูลนี้ในโค้ด An example is a commit message describing a subtle problem that motivated a code change. ตัวอย่างคือ commit message ที่อธิบายปัญหาที่ละเอียดอ่อนซึ่งกระตุ้นให้เกิดการเปลี่ยนแปลงโค้ด If this isn't documented in the code, then a developer might come along later and undo the change without realizing that they have re-created a bug. หากไม่ได้ document ไว้ในโค้ด นักพัฒนาอาจเข้ามาทีหลังและเลิกทำการเปลี่ยนแปลงโดยไม่ตระหนักว่าพวกเขาได้สร้าง bug ใหม่ If you want to include a copy of this information in the commit message as well, that's fine, but the most important thing is to get it in the code. หากคุณต้องการรวมสำเนาของข้อมูลนี้ใน commit message ด้วย นั่นก็ได้ แต่สิ่งที่สำคัญที่สุดคือการนำเข้าไปในโค้ด This illustrates the principle of placing documentation in the place where developers are most likely to see it; the commit log is rarely that place. นี่แสดงหลักการของการวาง documentation ในสถานที่ที่นักพัฒนามีแนวโน้มที่จะเห็นมากที่สุด commit log ไม่ค่อยเป็นสถานที่นั้น

16.4 Maintaining comments: avoid duplication (รักษาความเห็น: หลีกเลี่ยงการซ้ำซ้อน)

The second technique for keeping comments up to date is to avoid duplication. เทคนิคที่สองในการให้ความเห็นทันสมัยคือการหลีกเลี่ยงการซ้ำซ้อน If documentation is duplicated, it is more difficult for developers to find and update all of the relevant copies. หากเอกสารถูกซ้ำซ้อน นักพัฒนาจะยากขึ้นในการค้นหาและอัปเดตสำเนาที่เกี่ยวข้องทั้งหมด Instead, try to document each design decision exactly once. แต่อย่างไรก็ตาม พยายาม document แต่ละการตัดสินใจในการออกแบบเพียงครั้งเดียวเท่านั้น If there are multiple places in the code that are affected by a particular decision, don't repeat the documentation at each of these points. หากมีหลายสถานที่ในโค้ดที่ได้รับผลกระทบจากการตัดสินใจโดยเฉพาะ อย่าทำซ้ำ documentation ที่สถานที่เหล่านี้ Instead, find the most obvious single place to put the documentation. แต่อย่างไรก็ตาม ค้นหาสถานที่เดียวที่ชัดเจนที่สุดในการวาง documentation For example, suppose there is tricky behavior related to a variable, which affects several different places where the variable is used. ตัวอย่างเช่น สมมติว่ามีพฤติกรรมที่หลอกลวงที่เกี่ยวข้อง กับตัวแปร ซึ่งส่งผลต่อหลายสถานที่ที่ใช้ตัวแปร You can document that behavior in the comment next to the variable's declaration. คุณสามารถ document พฤติกรรมนั้นไว้ในความเห็นถัดจากการประกาศของตัวแปร This is a natural place that developers are likely to check if they're having trouble understanding code that uses the variable. นี่เป็นสถานที่ที่เป็นธรรมชาติซึ่งนักพัฒนามีแนวโน้มที่จะตรวจสอบหากพวกเขามีปัญหาในการเข้าใจโค้ดที่ใช้ตัวแปร

If there is no "obvious" single place to put a particular piece of documentation where developers will find it, create a designNotes file as described in Section 13.7. หากไม่มี "ชัดเจน" สถานที่เดียวในการวาง documentation เฉพาะที่นักพัฒนาจะหา ให้สร้างไฟล์ designNotes ตามที่อธิบายไว้ใน Section 13.7 Or, pick the best of the available places and put the documentation there. หรือ เลือกสิ่งที่ดีที่สุดจากสถานที่ที่มีอยู่และวาง documentation ไว้ที่นั่น In addition, add short comments in the other places that refer to the central location: "See the comment in xyz for an explanation of the code below." นอกจากนี้ เพิ่มความเห็นสั้น ๆ ในสถานที่อื่น ๆ ที่อ้างถึงตำแหน่งกลาง: "ดูความเห็นใน xyz สำหรับคำอธิบายของโค้ดด้านล่าง" If the reference becomes obsolete because the master comment was moved or deleted, this inconsistency will be self-evident because developers won't find the comment at the indicated place; they can use revision control history to find out what happened to the comment and then update the reference. หากการอ้างอิงกลายเป็นสิ่งที่ล้าสมัยเพราะความเห็น master ถูกย้ายหรือลบ ความไม่สอดคล้องนี้จะชัดเจนโดยตัวมันเอง เพราะนักพัฒนาจะไม่พบความเห็นที่สถานที่ที่ระบุ พวกเขาสามารถใช้ revision control history เพื่อหาสิ่งที่เกิดขึ้นกับความเห็นและจากนั้นอัปเดตการอ้างอิง In contrast, if the documentation is duplicated and some of the copies don't get updated, there will be no indication to developers that they are using stale information. ในทางตรงกันข้าม หากเอกสารถูกซ้ำซ้อนและสำเนาบางส่วนไม่ได้รับการอัปเดต จะไม่มีการระบุให้นักพัฒนาว่าพวกเขากำลังใช้ข้อมูลที่เก่า

Don't redocument one module's design decisions in another module. อย่า redocument การตัดสินใจในการออกแบบของหน่วยโค้ดหนึ่งไปยังหน่วยโค้ดอื่น For example, don't put comments before a method call that explain what happens in the called method. ตัวอย่างเช่น อย่าใส่ความเห็นก่อนการเรียก method ที่อธิบายสิ่งที่เกิดขึ้นใน method ที่ถูกเรียก If readers want to know, they should look at the interface comments for the method. หากผู้อ่านต้องการทราบ พวกเขาควรดู interface comments สำหรับ method Good development tools will usually provide this information automatically, for example, by displaying the interface comments for a method if you select the method's name or hover the mouse over it. เครื่องมือพัฒนาที่ดีมักจะให้ข้อมูลนี้โดยอัตโนมัติ ตัวอย่างเช่น โดยแสดง interface comments สำหรับ method หากคุณเลือกชื่อ method หรือเลื่อนเมาส์ไปเหนือ Try to make it easy for developers to find appropriate documentation, but don't do it by repeating the documentation. พยายามทำให้นักพัฒนาสามารถค้นหา documentation ที่เหมาะสมได้ง่าย แต่อย่าทำเช่นนั้นโดยทำซ้ำ documentation

If information is already documented someplace outside your program, don't repeat the documentation inside the program; just reference the external documentation. หากข้อมูลถูก document ไว้แล้วที่ใดที่หนึ่งนอกโปรแกรมของคุณ อย่าทำซ้ำ documentation ภายในโปรแกรม เพียงอ้างอิง documentation ภายนอก For example, if you write a class that implements the HTTP protocol, there's no need for you to describe the HTTP protocol inside your code. ตัวอย่างเช่น หากคุณเขียน class ที่นำ HTTP protocol ไปใช้ ไม่จำเป็นต้องอธิบาย HTTP protocol ภายในโค้ดของคุณ There are already numerous sources for this documentation on the Web; just add a short comment to your code with a URL for one of these sources. มีแหล่งข้อมูลมากมายสำหรับ documentation นี้บน Web แล้ว เพียงเพิ่มความเห็นสั้น ๆ ลงในโค้ดของคุณที่มี URL สำหรับแหล่งข้อมูลหนึ่งนี้ Another example is features that are already documented in a user manual. ตัวอย่างอื่นคือฟีเจอร์ที่มี documentation ในคู่มือผู้ใช้แล้ว Suppose you are writing a program that implements a collection of commands, with one method responsible for implementing each command. สมมติว่าคุณกำลังเขียนโปรแกรมที่นำชุดคำสั่งไปใช้ โดย method หนึ่งต้องรับผิดชอบสำหรับการนำคำสั่งแต่ละคำไปใช้ If there is a user manual that describes those commands, there's no need to duplicate this information in the code. หากมีคู่มือผู้ใช้ที่อธิบายคำสั่งเหล่านั้น ไม่จำเป็นต้องซ้ำซ้อนข้อมูลนี้ในโค้ด Instead, include a short note like the following in the interface comment for each command method: แต่อย่างไรก็ตาม รวมหมายเหตุสั้น ๆ เช่นต่อไปนี้ใน interface comment สำหรับแต่ละ method คำสั่ง:

// Implements the Foo command; see the user manual for details.

It's important that readers can easily find all the documentation needed to understand your code, but that doesn't mean you have to write all of that documentation. สิ่งสำคัญคือผู้อ่านสามารถค้นหา documentation ทั้งหมดที่จำเป็นเพื่อทำความเข้าใจโค้ดของคุณได้อย่างง่ายดาย แต่นั่นไม่ได้หมายความว่าคุณต้องเขียน documentation ทั้งหมดนั้น

16.5 Maintaining comments: check the diffs (รักษาความเห็น: ตรวจสอบ diffs)

One good way to make sure documentation stays up to date is to take a few minutes before committing a change to your revision control system to scan over all the changes for that commit; make sure that each change is properly reflected in the documentation. วิธีที่ดีหนึ่งวิธีในการให้แน่ใจว่า documentation ทันสมัยคือใช้เวลาสักครู่ก่อนที่จะ commit การเปลี่ยนแปลงไปยัง revision control system เพื่อสแกนการเปลี่ยนแปลงทั้งหมดสำหรับ commit นั้น ให้แน่ใจว่าการเปลี่ยนแปลงแต่ละรายการจะสะท้อนในอย่างเหมาะสมใน documentation These pre-commit scans will also detect several other problems, such as accidentally leaving debugging code in the system or failing to fix TODO items. การสแกน pre-commit เหล่านี้จะตรวจพบปัญหาอื่น ๆ เช่น การปล่อยโค้ดการแก้จุดบกพร่องอย่างไม่ตั้งใจในระบบหรือไม่ได้แก้ไข TODO items

16.6 Higher-level comments are easier to maintain (ความเห็นระดับสูงกว่าง่ายต่อการรักษา)

One final thought on maintaining documentation: comments are easier to maintain if they are higher-level and more abstract than the code. ข้อคิดสุดท้ายเกี่ยวกับการรักษา documentation: ความเห็นจะสูงขึ้นและเป็นนามธรรมมากขึ้นกว่าโค้ด These comments do not reflect the details of the code, so they will not be affected by minor code changes; only changes in overall behavior will affect these comments. ความเห็นเหล่านี้ไม่ได้สะท้อนรายละเอียดของโค้ด ดังนั้นจึงจะไม่ได้รับผลกระทบจากการเปลี่ยนแปลงโค้ดเล็กน้อย เฉพาะการเปลี่ยนแปลงพฤติกรรมโดยรวมเท่านั้นที่จะส่งผลกระทบต่อความเห็นเหล่านี้ Of course, as discussed in Chapter 13, some comments do need to be detailed and precise. แน่นอนว่า ดังที่กล่าวถึงใน บทที่ 13 ความเห็นบางประการจำเป็นต้องมีรายละเอียดและแม่นยำ But in general, the comments that are most useful (they don't simply repeat the code) are also easiest to maintain. แต่โดยทั่วไป ความเห็นที่มีประโยชน์มากที่สุด (พวกเขาไม่เพียงแต่ทำซ้ำโค้ด) ก็ยังง่ายต่อการจัดการ