326: Blow Your Redo Stack

Comment Philosophy

The discussion on comment writing philosophy highlights the importance of clarity and purpose in code documentation. Marco Arment argues that comments should not merely explain what the code does, as this can lead to unnecessary clutter. Instead, they should focus on the reasoning behind the code, providing context that isn't immediately obvious from the code itself 1. Casey Liss adds that understanding the 'why' behind code can transform one's approach to writing comments, making them more meaningful and insightful 2.

The best comments you see... are about the why and about the overall design.

--- Marco Arment

Effective comments are seen as a skill, with Marco emphasizing the importance of documenting the overall design and purpose of code rather than individual lines 3.

   

Legacy Challenges

Legacy code presents unique challenges, as Casey Liss recalls from his experience with outdated systems at Northrop Grumman. He describes working with a C codebase that lacked modern conveniences like a standard template library, making version control cumbersome and manual 4. Marco Arment shares frustrations about the lack of version control education in schools, noting that students often resort to rudimentary methods like file naming for versioning 5.

It's incredible to me that I was able to graduate... and still haven't had never used version control at the time.

--- Casey Liss

Documenting decisions in legacy code is crucial, as it helps future developers understand the rationale behind seemingly odd choices. Marco stresses the importance of leaving clear instructions on when and how to safely modify or remove outdated code 6.