To document or not to document? That is the question

⚠️ Warning: Contain excuses not to write documentation

Other people:
"𝘊𝘰𝘥𝘦 𝘥𝘰𝘤𝘶𝘮𝘦𝘯𝘵𝘢𝘵𝘪𝘰𝘯 𝘪𝘴 𝘢𝘯 𝘪𝘯𝘷𝘦𝘴𝘵𝘮𝘦𝘯𝘵 𝘵𝘰 𝘺𝘰𝘶𝘳 𝘧𝘶𝘵𝘶𝘳𝘦 𝘴𝘦𝘭𝘧 𝘢𝘯𝘥 𝘺𝘰𝘶𝘳 𝘵𝘦𝘢𝘮."

Me:
"𝘐𝘧 𝘺𝘰𝘶 𝘩𝘢𝘷𝘦 𝘵𝘰 𝘦𝘹𝘱𝘭𝘢𝘪𝘯, 𝘪𝘵 𝘸𝘢𝘴 𝘯𝘰𝘵 𝘤𝘭𝘦𝘢𝘳 𝘪𝘯 𝘵𝘩𝘦 𝘧𝘪𝘳𝘴𝘵 𝘱𝘭𝘢𝘤𝘦."

Instead of adding tons of comments, make the code more readable itself:

❌ 𝐃𝐎𝐍'𝐓: Add a comment to explain cryptic vars

// 𝘔𝘶𝘭𝘵𝘪𝘱𝘭𝘺 𝘱𝘳𝘪𝘤𝘦 𝘣𝘺 𝘲𝘶𝘢𝘯𝘵𝘪𝘵𝘺 𝘵𝘰 𝘨𝘦𝘵 𝘵𝘰𝘵𝘢𝘭 𝘤𝘰𝘴𝘵
𝘭𝘦𝘵 𝘹 = 𝘺 * 𝘻;

✅ 𝐃𝐎: Change var names to make them clearer

𝘭𝘦𝘵 𝘵𝘰𝘵𝘢𝘭𝘊𝘰𝘴𝘵 = 𝘱𝘳𝘪𝘤𝘦 * 𝘲𝘶𝘢𝘯𝘵𝘪𝘵𝘺;

or

❌ 𝐃𝐎𝐍'𝐓: Explain logic with a comment

// 𝘊𝘩𝘦𝘤𝘬 𝘪𝘧 𝘵𝘩𝘦 𝘶𝘴𝘦𝘳 𝘪𝘴 𝘢𝘯 𝘢𝘥𝘮𝘪𝘯 𝘢𝘯𝘥 𝘩𝘢𝘴 𝘱𝘦𝘳𝘮𝘪𝘴𝘴𝘪𝘰𝘯
𝘪𝘧 (𝘶 === 1 && 𝘱 > 3) { 
 𝘳𝘶𝘯();
}

✅ 𝐃𝐎: Change variables and function names

𝘭𝘦𝘵 𝘪𝘴𝘈𝘥𝘮𝘪𝘯 = 𝘶𝘴𝘦𝘳𝘙𝘰𝘭𝘦 === '𝘢𝘥𝘮𝘪𝘯';
𝘭𝘦𝘵 𝘩𝘢𝘴𝘗𝘦𝘳𝘮𝘪𝘴𝘴𝘪𝘰𝘯 = 𝘱𝘦𝘳𝘮𝘪𝘴𝘴𝘪𝘰𝘯𝘓𝘦𝘷𝘦𝘭 > 3;

𝘪𝘧 (𝘪𝘴𝘈𝘥𝘮𝘪𝘯 && 𝘩𝘢𝘴𝘗𝘦𝘳𝘮𝘪𝘴𝘴𝘪𝘰𝘯) { 
 𝘨𝘳𝘢𝘯𝘵𝘈𝘤𝘤𝘦𝘴𝘴(); 
}

Last:
Practice reading code, not documentation.

DRY: Don't repeat yourself
If your code is clear, there's no reason to repeat what it says.

Imagine this:

// 𝘔𝘶𝘭𝘵𝘪𝘱𝘭𝘺 𝘱𝘳𝘪𝘤𝘦 𝘣𝘺 𝘲𝘶𝘢𝘯𝘵𝘪𝘵𝘺 𝘵𝘰 𝘨𝘦𝘵 𝘵𝘰𝘵𝘢𝘭 𝘤𝘰𝘴𝘵
𝘭𝘦𝘵 𝘵𝘰𝘵𝘢𝘭𝘊𝘰𝘴𝘵 = 𝘱𝘳𝘪𝘤𝘦 * 𝘲𝘶𝘢𝘯𝘵𝘪𝘵𝘺;

or

// 𝘊𝘩𝘦𝘤𝘬 𝘪𝘧 𝘵𝘩𝘦 𝘶𝘴𝘦𝘳 𝘪𝘴 𝘢𝘯 𝘢𝘥𝘮𝘪𝘯 𝘢𝘯𝘥 𝘩𝘢𝘴 𝘱𝘦𝘳𝘮𝘪𝘴𝘴𝘪𝘰𝘯
𝘭𝘦𝘵 𝘪𝘴𝘈𝘥𝘮𝘪𝘯 = 𝘶𝘴𝘦𝘳𝘙𝘰𝘭𝘦 === '𝘢𝘥𝘮𝘪𝘯';
𝘭𝘦𝘵 𝘩𝘢𝘴𝘗𝘦𝘳𝘮𝘪𝘴𝘴𝘪𝘰𝘯 = 𝘱𝘦𝘳𝘮𝘪𝘴𝘴𝘪𝘰𝘯𝘓𝘦𝘷𝘦𝘭 > 3;

𝘪𝘧 (𝘪𝘴𝘈𝘥𝘮𝘪𝘯 && 𝘩𝘢𝘴𝘗𝘦𝘳𝘮𝘪𝘴𝘴𝘪𝘰𝘯) { 
 𝘨𝘳𝘢𝘯𝘵𝘈𝘤𝘤𝘦𝘴𝘴(); 
}

That's ridiculous.
That's when you know your code is clear.
No explanations needed.

---

𝐙𝐄𝐍 𝐎𝐅 𝐏𝐘𝐓𝐇𝐎𝐍 (𝘡𝘦𝘯 𝘰𝘧 𝘌𝘷𝘦𝘳𝘺𝘵𝘩𝘪𝘯𝘨)

𝐁𝐞𝐚𝐮𝐭𝐢𝐟𝐮𝐥 𝐢𝐬 𝐛𝐞𝐭𝐭𝐞𝐫 𝐭𝐡𝐚𝐧 𝐮𝐠𝐥𝐲. 👈

𝐄𝐱𝐩𝐥𝐢𝐜𝐢𝐭 𝐢𝐬 𝐛𝐞𝐭𝐭𝐞𝐫 𝐭𝐡𝐚𝐧 𝐢𝐦𝐩𝐥𝐢𝐜𝐢𝐭. 👈

𝐒𝐢𝐦𝐩𝐥𝐞 𝐢𝐬 𝐛𝐞𝐭𝐭𝐞𝐫 𝐭𝐡𝐚𝐧 𝐜𝐨𝐦𝐩𝐥𝐞𝐱. 👈

𝐂𝐨𝐦𝐩𝐥𝐞𝐱 𝐢𝐬 𝐛𝐞𝐭𝐭𝐞𝐫 𝐭𝐡𝐚𝐧 𝐜𝐨𝐦𝐩𝐥𝐢𝐜𝐚𝐭𝐞𝐝.

𝐅𝐥𝐚𝐭 𝐢𝐬 𝐛𝐞𝐭𝐭𝐞𝐫 𝐭𝐡𝐚𝐧 𝐧𝐞𝐬𝐭𝐞𝐝.

𝐒𝐩𝐚𝐫𝐬𝐞 𝐢𝐬 𝐛𝐞𝐭𝐭𝐞𝐫 𝐭𝐡𝐚𝐧 𝐝𝐞𝐧𝐬𝐞.

𝐑𝐞𝐚𝐝𝐚𝐛𝐢𝐥𝐢𝐭𝐲 𝐜𝐨𝐮𝐧𝐭𝐬. 👈

𝐒𝐩𝐞𝐜𝐢𝐚𝐥 𝐜𝐚𝐬𝐞𝐬 𝐚𝐫𝐞𝐧'𝐭 𝐬𝐩𝐞𝐜𝐢𝐚𝐥 𝐞𝐧𝐨𝐮𝐠𝐡 𝐭𝐨 𝐛𝐫𝐞𝐚𝐤 𝐭𝐡𝐞 𝐫𝐮𝐥𝐞𝐬.

𝐀𝐥𝐭𝐡𝐨𝐮𝐠𝐡 𝐩𝐫𝐚𝐜𝐭𝐢𝐜𝐚𝐥𝐢𝐭𝐲 𝐛𝐞𝐚𝐭𝐬 𝐩𝐮𝐫𝐢𝐭𝐲.

𝐄𝐫𝐫𝐨𝐫𝐬 𝐬𝐡𝐨𝐮𝐥𝐝 𝐧𝐞𝐯𝐞𝐫 𝐩𝐚𝐬𝐬 𝐬𝐢𝐥𝐞𝐧𝐭𝐥𝐲.

𝐔𝐧𝐥𝐞𝐬𝐬 𝐞𝐱𝐩𝐥𝐢𝐜𝐢𝐭𝐥𝐲 𝐬𝐢𝐥𝐞𝐧𝐜𝐞𝐝.

𝐈𝐧 𝐭𝐡𝐞 𝐟𝐚𝐜𝐞 𝐨𝐟 𝐚𝐦𝐛𝐢𝐠𝐮𝐢𝐭𝐲, 𝐫𝐞𝐟𝐮𝐬𝐞 𝐭𝐡𝐞 𝐭𝐞𝐦𝐩𝐭𝐚𝐭𝐢𝐨𝐧 𝐭𝐨 𝐠𝐮𝐞𝐬𝐬.

𝐓𝐡𝐞𝐫𝐞 𝐬𝐡𝐨𝐮𝐥𝐝 𝐛𝐞 𝐨𝐧𝐞-- 𝐚𝐧𝐝 𝐩𝐫𝐞𝐟𝐞𝐫𝐚𝐛𝐥𝐲 𝐨𝐧𝐥𝐲 𝐨𝐧𝐞 --𝐨𝐛𝐯𝐢𝐨𝐮𝐬 𝐰𝐚𝐲 𝐭𝐨 𝐝𝐨 𝐢𝐭. 👈

𝐀𝐥𝐭𝐡𝐨𝐮𝐠𝐡 𝐭𝐡𝐚𝐭 𝐰𝐚𝐲 𝐦𝐚𝐲 𝐧𝐨𝐭 𝐛𝐞 𝐨𝐛𝐯𝐢𝐨𝐮𝐬 𝐚𝐭 𝐟𝐢𝐫𝐬𝐭 𝐮𝐧𝐥𝐞𝐬𝐬 𝐲𝐨𝐮'𝐫𝐞 𝐃𝐮𝐭𝐜𝐡.

𝐍𝐨𝐰 𝐢𝐬 𝐛𝐞𝐭𝐭𝐞𝐫 𝐭𝐡𝐚𝐧 𝐧𝐞𝐯𝐞𝐫.

𝐀𝐥𝐭𝐡𝐨𝐮𝐠𝐡 𝐧𝐞𝐯𝐞𝐫 𝐢𝐬 𝐨𝐟𝐭𝐞𝐧 𝐛𝐞𝐭𝐭𝐞𝐫 𝐭𝐡𝐚𝐧 𝐫𝐢𝐠𝐡𝐭 𝐧𝐨𝐰.

𝐈𝐟 𝐭𝐡𝐞 𝐢𝐦𝐩𝐥𝐞𝐦𝐞𝐧𝐭𝐚𝐭𝐢𝐨𝐧 𝐢𝐬 𝐡𝐚𝐫𝐝 𝐭𝐨 𝐞𝐱𝐩𝐥𝐚𝐢𝐧, 𝐢𝐭'𝐬 𝐚 𝐛𝐚𝐝 𝐢𝐝𝐞𝐚. 👈

𝐈𝐟 𝐭𝐡𝐞 𝐢𝐦𝐩𝐥𝐞𝐦𝐞𝐧𝐭𝐚𝐭𝐢𝐨𝐧 𝐢𝐬 𝐞𝐚𝐬𝐲 𝐭𝐨 𝐞𝐱𝐩𝐥𝐚𝐢𝐧, 𝐢𝐭 𝐦𝐚𝐲 𝐛𝐞 𝐚 𝐠𝐨𝐨𝐝 𝐢𝐝𝐞𝐚.

𝐍𝐚𝐦𝐞𝐬𝐩𝐚𝐜𝐞𝐬 𝐚𝐫𝐞 𝐨𝐧𝐞 𝐡𝐨𝐧𝐤𝐢𝐧𝐠 𝐠𝐫𝐞𝐚𝐭 𝐢𝐝𝐞𝐚 – 𝐥𝐞𝐭'𝐬 𝐝𝐨 𝐦𝐨𝐫𝐞 𝐨𝐟 𝐭𝐡𝐨𝐬𝐞! 👈