diff --git a/src/content/daily-email/2023-07-21.md b/src/content/daily-email/2023-07-21.md new file mode 100644 index 00000000..7a5a2aab --- /dev/null +++ b/src/content/daily-email/2023-07-21.md @@ -0,0 +1,18 @@ +--- +title: > + Comments as communication +pubDate: 2023-07-21 +permalink: > + archive/2023/07/21/comments-as-communication +tags: [] +--- + +I often hear that code should be "self-documenting". + +Instead of writing a comment, you should create a function or class with that name instead. + +Whilst I agree with this, I think that code comments shouldn't describe what the code is doing - they should explain why the code is needed and provide any additional context to the person reading it. + +If a comment just says `Returns true` or `Sends an email`, that can be understood by reading the code, so isn't providing any extra value or context. They can also become outdated as the code changes. + +If a line of code is needed to fix a certain state or situation, or if a piece of code isn't particularly readable and isn't obvious what it does, those are good times to add comments.