In this learning session, I explored the clean code technique of using comments effectively in code and files. I learned about the situations in which comments are appropriate and the types of comments to avoid.
I understood that comments should not be used as a way to cover up poorly written or confusing code. Instead, I learned that the focus should be on improving the code itself through the use of principles, patterns, and good coding practices.
I learned the importance of prioritizing meaningful and descriptive names for variables, functions, classes, and files. By choosing clear and self-explanatory names, we can reduce the need for comments to explain the purpose or functionality of the code.
I explored different types of comments that can be considered good practice in code. These include legal comments (e.g., copyright information), informative comments (e.g., explaining complex algorithms or data structures), comments that clarify intent (e.g., explaining the reasoning behind a particular implementation choice), and TODO comments (e.g., indicating future improvements or tasks).
I learned about various types of comments that should be avoided in code. These include mumbling comments (e.g., comments that provide no meaningful information), misleading comments (e.g., comments that lead to misunderstanding or confusion), noise comments (e.g., comments that state the obvious or reiterate the code), mandated comments (e.g., comments that are required by coding guidelines but add no value), and attribution and bylines comments (e.g., comments that credit the author but provide no useful information).
By understanding when and how to use comments effectively, I gained insights into creating clean and readable code. I learned to prioritize clear and descriptive code over excessive comments, use comments to provide valuable information and explanations, and avoid comments that add no value or lead to confusion.