opdavies/oliverdavies.uk
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

daily-email: add 2023-07-21

Browse source 
Comments as communication
This commit is contained in:
Oliver Davies 2023-07-22 11:00:52 +01:00
parent 80ef277296
commit d1ae3be377
1 changed files with 18 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
src/content/daily-email/2023-07-21.md Normal file
View file

@ -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.