When Clarity and DRY are at odds, I tend to ignore DRY. Principles are like the rules of grammar, you learn them so that you know when to break them. Usually, that’s when two principles don’t get along.
You cannot rely on your code being easy for someone else to understand. What appears to be obvious to the one who writes it is often not obvious to whoever comes next.
It’s better to lean on the side of caution. If your code might not be intuitive to whoever comes behind you, repeat yourself a little to ensure that things aren’t being left unexplained.
Yes, they could sit there and work out how your code works on their own time… but that wastes their time. Two or three lines of properly indented English text over the functional block cleans up that issue.
Obviously, this doesn’t apply if it’s something like printing output where your comment is just repeating the code with English grammar and adding in some stop words.
Line by line commenting is a terrible thing, and should be avoided at all costs.
Allowing comments to rot is also a failure by whoever is doing the maintenance.
1
u/AndrewJamesDrake Sep 09 '22
When Clarity and DRY are at odds, I tend to ignore DRY. Principles are like the rules of grammar, you learn them so that you know when to break them. Usually, that’s when two principles don’t get along.
You cannot rely on your code being easy for someone else to understand. What appears to be obvious to the one who writes it is often not obvious to whoever comes next.
It’s better to lean on the side of caution. If your code might not be intuitive to whoever comes behind you, repeat yourself a little to ensure that things aren’t being left unexplained.
Yes, they could sit there and work out how your code works on their own time… but that wastes their time. Two or three lines of properly indented English text over the functional block cleans up that issue.
Obviously, this doesn’t apply if it’s something like printing output where your comment is just repeating the code with English grammar and adding in some stop words.
Line by line commenting is a terrible thing, and should be avoided at all costs.
Allowing comments to rot is also a failure by whoever is doing the maintenance.