In many years of consulting, I’ve seen a lot of projects developed with the philosophy of “Don’t worry about [comments][readable code][proper variable names][documentation][error handling][optimization][(your favorite corner to cut here)] because this is just a prototype – we’ll fix those things when we write the production code.” In 100% of those cases, when the prototype was reasonably close to working, it got shipped: The “prototype” became the production code, errors, shortcomings and all. Maintenance, updates and improvements became nightmares, often leading to complete failure of what could have been a great product. Trying to avoid those problems feeds into my OCD tendencies, and when I see a comment like “we’ll write another [CR] to fix it” I tend to balk because I know the rewrite will never happen. Furthermore, when a future developer is called on to fix a bug or develop a new feature, they’re going to be “strongly” discouraged from making any changes beyond their immediate effort, even if renaming variables would make the code more readable when they discovered “flag” is “page_type” or “std” means “start_date” instead of “standard” etc. Having an understandable, well documented interface from the beginning is a LOT more important than making all of the internal variables recognizable. “Cosmetic changes” often look a lot less trivial when you realize that the lifetime cost of code maintenance is generally ten times what it cost for a program to be written initially.

I recognize that I have to reign in my OCD to let development proceed. However, when a developer asks someone to review their code, they need to recognize the reviewer is looking at it from a different perspective than they are. If a reviewer doesn’t understand something, it could either be an error or a misunderstanding. When a misunderstanding is encountered, commenting on a change request doesn’t help the next person reading the code, and adding a comment to the code at this point isn’t a lot of effort. It will, though, make the code more maintainable – it reduces the maintenance cost. Also, if a native English speaker hands a foreign born developer a well written docstring that clarifies a point of confusion, it’s not just courteous to use it: You’re not going to break anything by putting the brakes on for a moment and push one more patch set.