To document or not to document? That is the question

#webdev #programming #beginners

⚠️ 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

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

❌ 𝐃𝐎𝐍'𝐓: 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:

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

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

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

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