Dear Future Me: Please Document Your Code!

It was 9 PM, and my coffee had gone cold. I stared at the code. The code stared at me. Who was going to break first? With every passing second, my eyes widened in horror.

• What does ‘x’ mean here?

• Why is this function named fnc1?

• Was I even the one who wrote this??

And then—I broke first.

"WHO WROTE YOU?!" I yelled at the screen, flinging my laptop out the window. (No, I didn’t actually throw it. My mom would kill me ❣️).

Anyways, long story short, I rewrote the whole thing. Aggressively. (But I added comments this time!)

---

At least once in your programming life, you have had that moment where you stared at your old code cluelessly, not understanding what does what. Instead of spending your time adding more features to your code, you wasted it trying to piece the code together so that it makes sense. Reason for that:

“You forget to document your code properly.”

---

Why This Happens to All of Us

We all think we’ll remember what our code does. We all think our logic is crystal clear. And yet, a few weeks later, we stare at our own work like it’s an alien language.

Why? Because we tell ourselves these lies:

❌ "I’ll remember this later." (No, you won’t.)
❌ "The variable names make sense!" (No, they don’t. ‘x’ and ‘y’ mean nothing to Future You.)
❌ "I left a comment somewhere, I think?" (Yeah, one lonely ‘//fix this later’ isn’t helping anyone.)
❌ "This function is so simple, it doesn’t need comments!" (Then why are you confused now?)
❌ "I'll just add a TODO and get back to it." (Your TODO list is basically a graveyard now.)
❌ "If anyone needs help understanding this, they can just ask me!" (Future You is the one who needs help.)
❌ "I’ll clean this up before pushing it." (No, you’ll push it and run. We all know it.)
❌ "I don’t need documentation, the code is self-explanatory!" (Who’s staring at the code cluelessly now?)

---

How to start documenting your code properly

Instead of leaving Future You clueless and angry, here’s how to document code.

1. Write Comments That Actually Help

Comments should explain why something is happening—not just what is happening.

🚫 Bad Comment:

// This function sorts an array
function sortArray(arr) {
    return arr.sort();
}

❌ Thanks, Captain Obvious. We all know what .sort() does.

✅ Better Comment:

// Sorts numbers in ascending order, including negatives
function sortArray(arr) {
    return arr.sort((a, b) => a - b);
}

👆 Now Future You actually understands the function’s intent!

---

2. Stop Using Cryptic Variable Names

You might think x, a1, or tempVar make sense now, but trust me—they won’t in two weeks.

🚫 Terrible Naming:

let x = 5;
function fnc1() {
    return x * 2;
}

✅ Better Naming:

let baseMultiplier = 5;
function doubleValue() {
    return baseMultiplier * 2;
}

💡 Rule of Thumb: If you need a comment to explain a variable, you probably just need a better name.

---

3. Leave a Quick "Gotchas" Note

Ever spent hours debugging, only to realize you already knew the issue last time but forgot to document it?

🚫 Future You (panicking): "Why does this function break when the input is empty?!"
✅ Past You (being kind):

// NOTE: This function fails if input is not an array. Validate before calling.
function processData(arr) {
    return arr.map(item => item * 2);
}

💡 Leaving small "warnings" like this can save you hours of frustration.

---

4. Write a Tiny ReadMe (Yes, Even for Small Projects!)

A ReadMe doesn’t need to be a novel. Even five lines can be a lifesaver:

# NerdyNotes 📓  
A markdown-supported note-taking app.  

## Setup  
1. Clone the repo: `git clone https://github.com/yourrepo/nerdynotes.git`  
2. Install dependencies: `npm install`  
3. Start the project: `npm start`

💡 This simple ReadMe will save you (or your team) from struggling with setup later.

---

Final Thoughts

So, dear Future Me:

• I promise to write better comments.

• I promise to stop naming things tempFinal1_revised.

• I promise to leave helpful notes so I don’t rage-quit my own code.

Because if I don’t… I know exactly what’s coming.

"WHO WROTE THIS?!"

Oh. Right. It was me.