re: Should comments in code be considered failures in coding? VIEW POST

re: This is false dichotomy that you can use only self-explanatory code or only comments. You can use both. Self-explanatory code can't answer the ques...

💯 this! We recently had a case where two keys in a 3rd party API response appear to return the value 99% of the time, and we were oblivious to that 1% until the 3rd party maintainer told us they were different.

To remove the need for comments in our code ingesting that API, we would have had to rename database table columns and change all of our internal naming conventions around that attribute - which would not have been possible because we integrate with multiple 3rd party APIs that all use their own naming conventions. So refactoring code to work for one API would require us adding comments to explain why the other API's responses didn't match up.

Instead of those code changes, a one-line comment explaining the why is all we'll need to do to clarify and prevent further confusion.


But that's very obviously a failure, right? A failure to communicate, receive or understand requirements properly. If that miscommunication wouldn't have happened and the comment is unnecessary. so in this case I would say it's very directly the comment communicates a failure in code.
Yes it's the easy option here and possibly the right one, but it's still required because of a failure. That is technical debt.

With the context of how this particular app is built and our limitations, I don't agree with that - and I think is the general gray area that I believe is unavoidable in most legacy codebases.

Even if we were to ignore the miscommunication that happened that resulted in us using the wrong key in the first place, we still have to rectify the differences between the different APIs that our app is ingesting to populate one database. As much as I would prefer it, sometimes you have to make a choice and stick with it - in this case, a tricky naming problem that doesn't have a solution that fits all sources of data.

I understand and agree with your general tenet, but the world isn't black and white and I think it's a dangerous mindset to think that there is a "right" way to write code that will guarantee other users will understand its purpose.

we still have to rectify the differences between the different APIs that our app is ingesting to populate one database

Which is why database objects are -in good design- considered separated from runtime objects so this sort of thing is easy and more flexible. Then they can be called whatever you like in your db.

You are saying that a mistake was made and it resulted in a comment but still defending the notion that comments don't indicate mistakes. You are using what many would consider to be bad design (tightly coupled runtime and domain objects with database objects) explained in comments as an argument that comments aren't always compensation for mistakes.

I know the world isn't black and white and there are exceptions to every rule and it's important to understand that but without the rule and pushing into that grey area as much as possible then the grey area pushes back, which seems to have happened quite strongly in the case you mention.

Readability of code depends on the reader 🤝. And sadly there is no single set of rules. Some people find Lisp hard to read, some work with it just fine. Some people prefer OOP-ish style of code some prefer functional-ish, and some prefer strange mix ¯\_(ツ)_/¯.

Some people would not find code self-explanatory even if others think it is. What to do in this case?

1) Explain code?
2) Instead of explaining it each time put this explanation in the codebase (in form of a comment)?
3) Rewrite code, until everybody agrees?

From my PoV, all can be valid options, depending on the situation. The situation can repeat whenever team working with this code changes, or changes are reviewed by one part of the team but on the other.

PS remembered about this: SPACE SHUTTLE code

Some people would not find code self-explanatory even if others think it is. What to do in this case?

Code review. Come to a consensus.

20 years a developer. I've never had a comment teach me anything about well written code.

But you agree that different people have different opinions on the readability of the code? And you strive for understanding in the team and you can reach it in the team, but then somebody new comes to the team and you may need to reconsider readability of the code. As well when people do review it is not done by the whole team, but only by the part of the team (depends on the size of the team), which means that part of the team may not consider code easy to read.

Different people have different opinions but there is a middle ground and we strive for that. It shouldn't be acceptable to say "I wrote unreadable code so I wrote a comment to explain it".

Code of Conduct Report abuse