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.
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".
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
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
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".