The Art of Code Comments

on YouTube ↗21m

" summary

Argues that comments must state the actual why not restate the how, shows browser-workaround comments (user‑agent hacks targeting old Firefox and Chrome/Safari/Opera), recommends marking temporary or deadline code with explicit flags so future maintainers can safely refactor, advises linking to Stack Overflow or original sources, stresses using version control instead of dead code, and cites 30% vs 70% coding vs reading to justify spending minutes improving or removing misleading comments.

AI-written summary · about

" chapters (6)

1. 0:00Start
2. 7:13COMMENTS CAN BE LIKE CHAPTERS OF A BOOK
3. 7:59A GUIDE TO KEEP THE LOGIC STRAIGHT WHILE WRITING THE CODE
4. 10:30COMMENTING AS A TEACHING TOOL
5. 14:02IT WASN'T WELL MAINTAINED
6. 16:41YOU COULD HAVE USED A BETTER NAME

" related talks

• 13mOn Readable CodeJared Wyles · Web Directions Code 2014
• 41mTo comment or notVeronica Hanus · PyData New York City 2019
• 24m//TODO: Write A Better CommentAdam McNeilly · droidcon NYC 2019
• 51mTechnically speaking improve your code documentationAlexandra White · DevFest Lille 2022
• 40mGood Code: What, Why, and How to Get ThereJane Prusakova · NDC London 2018
• 18mHow To Review Someone's Code While Not Being A Jerk!Maha Alsayasneh · DevFest Toulouse 2023
• 53mCode Review - how to do it better?Sebastian Malaca · Voxxed Days Ticino 2017
• 20mGood Code is a Balancing ActJonathan Warrington · Reliable Web Summit 2021