flâneur

Google Testing Blog: Less Is More: Principles for Simple Comments

testing.googleblog.com · 1,129 words · saved by 1 readers

You’re staring at a wall of code resembling a Gordian knot of Klingon. What’s making it worse? A sea of code comments so long that you’d need a bathroom break just to read them all! Let’s fix that. Adopt the mindset of someone unfamiliar with the project to ensure simplicity. One approach is to separate the process of writing your comments from reviewing them; proofreading your comments without code context in mind helps ensure they are clear and concise for future readers. Use self-contained comments to clearly convey intent without relying on the surrounding code for context. If you need to read the code to understand the comment, you’ve got it backwards! Not self-contained; requires reading the code Suggested alternative // Respond to flashing lights in // rearview mirror. // Pull over for police and/or yield to // emergency vehicles. while flashing_lights_in_rearview_mirror() { if !move_to_slower_lane() { stop_on_shoulder(); } } Include only essential information in t

Google Testing Blog: Less Is More: Principles for Simple Comments Testing Blog Less Is More: Principles for Simple Comments Wednesday, August 21, 2024 Google Labels: Code Health , David Bendory , TotT    Labels  TotT 113 GTAC 61 James Whittaker 42 Misko Hevery 32 Code Health 31 Anthony Vallone 27 Patrick Copeland 23 Jobs 18 Andrew Trenk 13 C++ 11 Patrik Höglund 8 JavaScript 7 Allen Hutchison 6 George Pirocanac 6 Zhanyong Wan 6 Harry Robinson 5 Java 5 Julian Harty 5 Adam Bender 4 Alberto Savoia 4 Ben Yu 4 Erik Kuefler 4 Philip Zembrod 4 Shyam Seshadri 4 Chrome 3

related reading