//TODO: Write A Better Comment
summary
Article that told developers to stop writing comments is rejected as bad advice and replaced with a practical plan: classify comments as remove redundant comments, unhelpful, or genuinely useful; eliminate comments by renaming methods or extracting functions; keep comments that explain why a workaround exists (example: an Epoxy interceptor plus an updated-questions map to show local answers over an immutable list); make comments actionable by linking to Jira or Stack Overflow, use IDE references so refs update on refactor, and be consistent in phrasing (always state the true condition for booleans).
AI-written summary · about
chapters (18)
- 0:00Introduction
- 0:47Java’s bad advice on comments
- 1:51Purpose of code comments
- 3:56Risks of outdated comments
- 5:43Three types of comments
- 6:25Removing unnecessary comments
- 7:49Code vs comments for clarity
- 9:32Writing helpful comments
- 10:15Comments should explain why
- 11:59Adding examples to comments
- 13:02Linking to resources
- 15:30Actionable to-do comments
- 16:52Deprecation with guidance
- 17:35General comment tips
- 18:16Summarizing code sections
- 18:58Referencing definitions
- 20:44Consistent comment language
- 21:49Summary and recap
