aleidk/master-wiki
1
0
Fork 0
Code Issues 11 Pull requests Projects Releases Packages Wiki Activity Actions

Update from obsidian - thinkpad

Browse source 
Affected files:
.obsidian/plugins/obsidian-omnivore/data.json
Read Later/How to Write Components that Work in Any Framework.md
Read Later/The Complete Guide to Time Blocking.md
Read Later/The First Rule of Comments in Code.md
projects/personal-page-notes/List of Games.md
projects/personal-page-notes/Use Table component to create Portafolio and Blog page.md
projects/personal-page.md
This commit is contained in:
Alexander Navarro 2023-11-11 12:35:42 -03:00
parent 740ac64ddb
commit 55cf54064d
7 changed files with 749 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

43
Read Later/The First Rule of Comments in Code.md Normal file
View file

@ -0,0 +1,43 @@
---
id: 24bd8d1e-b118-4930-a86d-3929f2dad34c
title: |
The First Rule of Comments in Code
status: ARCHIVED
tags:
- read-later
date_added: 2023-11-02 23:25:19
url_omnivore: |
https://omnivore.app/me/https-youtu-be-hxsx-3-vbf-qq-si-c-5-qy-m-mg-8-j-yhc-bbq-18b92ffccf6
url_original: |
https://youtu.be/hxsx3vbf-QQ?si=-C5QyMMg8JYhcBBQ
---
# The First Rule of Comments in Code
## Notes
Comments are bad by nature:
- They get outdated pretty quickly, and you don't know if the comments is updated with the code.
- A comments is most probably noise, because it's not gonna provide more information than the code itself.
- Commented code is broken code, because it's probably outdated compared to it's context.
Some rules to evade writing comments:
**Code that needs a comment, needs to be rewritten**. Always try to put the information in the code. if it needs a comment, it's not good enough.
**Move information somewhere else**. this is similar to the previous, move to a variable name, or to a documentation file in the worst case.
**How quickly the information will goes out of date**. It's so simple that a comments goes out of sync with the code, to prevent that transform the comment in code.
**If a comment gives no more information than the code, delete it**.
**"I need to explain the complexity"**. No, you need to fix the complexity. If the complexity is so big, put in the documentation instead. A comment cannot fix complexity, and will require hard work to change that code.
**Don't comment out code, delete it**. Commented code goes quickly out of sync with it's context, is not tested in any way and the effort of updating it is almost the same if not higher that writing it over with better knowledge, so it's better to just delete it. If we need this code back, we can recover it with git.
---
## Original
[The First Rule of Comments in Code](https://youtu.be/hxsx3vbf-QQ?si=-C5QyMMg8JYhcBBQ)
By [Bran van der Meer](https://www.youtube.com/@branvandermeer)