19 lines
870 B
Markdown
19 lines
870 B
Markdown
---
|
|
title: >
|
|
Comments as communication
|
|
pubDate: 2023-07-21
|
|
permalink: >-
|
|
daily/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.
|