Comment by actionfromafar
9 days ago
But the documentation can really help in telling why we are doing things. That also seeps in to naming things like classes. If that were not so, we'd just name everything Class1, Class2, Method1, Method2 and so on.
My point is that if your code is well written, it is self-documenting. Obviously Class1 and var2 are not self-documenting.
The code is what it does. The comments should contain what it's supposed to do.
Even if you give them equal roles, self-documenting code versus commented code is like having data on one disk versus having data in a RAID array.
Remember: Redundancy is a feature. Mismatches are information. Consider this:
// Calculate the sum of one and one
sum = 1 + 2;
You don't have to know anything else to see that something is wrong here. It could be that the comment is outdated, which has no direct effects and is easily solved. It could be that this is a bug in the code. In any case it is information and a great starting point for looking into a possible problem (with a simple git blame). Again, without needing any context, knowledge of the project or external documentation.
My take on developers arguing for self-documenting code is that they are undisciplined or do not use their tools well. The arguments against copious inline comments are "but people don't update them" and "I can see less of the code".
> Redundancy is a feature. Mismatches are information. Consider this:
Respectfully, if someone wrote code like this, I wouldn't want to work with them. I mean next step is "I copy paste code instead of writing functions, and in the comment above I mention all the other copies, so that it's easy to check that they are all doing the same thing redundantly".
> The arguments against copious inline comments are "but people don't update them" and "I can see less of the code".
Well no, that's not my argument. I have been navigating code for 20 years and in good codebases, comments are rare and describe something "surprising". Good code is hardly surprising.
My problem with "literate programming" (which means "add a lot of comments in the implementation details") is that I find it hard to trust developers who genuinely cannot understand unsurprising code without comments. I am fine with a junior needing more time to learn, but after a few years if a developer cannot do it, it concerns me.
2 replies →
def reallyDumbIdeaByManagerWorkaroundMethodToGetCoverageToNinetyPercent(self): """Dont worry, this is a clear description of the method. """ return False
You exaggerate, but in this situation, I think putting a link to a Jira ticket or Slack convo (or whatever) as comment is best