DEV Community


Discussion on: Should comments in code be considered failures in coding?

lukewestby profile image
Luke Westby • Edited

As a contradictory scenario, consider that a lot of popular languages and frameworks have core functions that are confusingly named or poorly documented or have unexpected behavior for particular sets of arguments. It’s not malicious; everyone generally does their best and choice quality deteriorates over time as expectations rise. But core functions are how we accomplish our goals on those platforms so we don’t have the choice to avoid them. I’m not sure how I would explain a specific use of such a function to future developers or warn them of its inherent and unavoidable precariousness without a code comment.

I’m not so much a fan of looking for general rules about code comments and quality to make judgements of highly contextual choices. I’m much happier accepting ambiguity and examining behavior in terms of the systems and externalities that shape it. On this subject in particular I’ve learned to understand that “this code is a failure” often just means “I personally don’t like it” and nothing more. I’ve read a lot of what Bob Martin has to say and I don’t really get the sense that he agrees.

rossdrew profile image
Ross Author

But again that describes a mistake, covered by a comment right? You are saying that yes, comments indicate mistakes but sometimes they are necessary. That's a different argument entirely.