--- ## Highlights So restrict your non-API commenting to discussing why something is done, its purpose and its goal. The code already shows how it is done, so commenting on this is redundant—and is a violation of the DRY principle. (Location 1118) Commenting source code gives you the perfect opportunity to document those elusive bits of a project that can’t be documented anywhere else: engineering trade-offs, why decisions were made, what other alternatives were discarded, and so on. (Location 1121) SUMMARY Know what you want to say. Know your audience. Choose your moment. Choose a style. Make it look good. Involve your audience. Be a listener. Get back to people. (Location 1123) There are several good books that contain sections on communications within teams, including The Mythical Man-Month: Essays on Software Engineering [Bro96] and Peopleware: Productive Projects and Teams [DL13]. Make it a point to try to read these over the next 18 months. In addition, Dinosaur Brains: Dealing with All Those Impossible People at Work [BR89] discusses the emotional baggage we all bring to the work environment. (Location 1169) Chapter 2 A Pragmatic Approach (Location 1229) A thing is well designed if it adapts to the people who use it. For code, that means it must adapt by changing. So we believe in the ETC principle: Easier to Change. ETC. That’s it. (Location 1280) You may need to spend a week or so deliberately asking yourself “did the thing I just did make the overall system easier or harder to change?” Do it when you save a file. Do it when you write a test. Do it when you fix a bug. (Location 1293) Get your editor to popup an ETC? message every time you save[14] and use it as a cue to think about the code you just wrote. Is it easy to change? (Location 1332) Whatever the reason, maintenance is not a discrete activity, but a routine part of the entire development process. (Location 1351) We feel that the only way to develop software reliably, and to make our developments easier to understand and maintain, is to follow what we call the DRY principle: Every piece of knowledge must have a single, unambiguous, authoritative representation within a system. Why do we call it DRY? Tip 15    DRY—Don’t Repeat Yourself (Location 1355) Somehow the myth was born that you should comment all your functions. Those who believe in this insanity then produce something such as this: (Location 1749) Ask yourself what the comment adds to the code. (Location 1833)