Anyway, great article. I agree that reputation is a strong motivator for polishing/refactoring.

Most of the changes I make when polishing code are indeed refactorings. Perhaps the one exception is adding or improving comments. I think the main difference is in intent: refactoring is focused only upon improving the design, whereas when I polish code my overall goal is to improve the maintainability of the code. This of course includes improving the design, but also addresses readability.

As for when to polish, I agree it could be done at different points in the software development life cycle. My article was focused on doing it on your code just after you have ‘finished’ writing it, both to challenge developers to create better code themselves, and because it fits the analogy of woodworking, where you polish a piece of wood as the final step. So while refactoring the code before you start to work on it often makes sense, to call that polishing goes against the grain of the analogy.

Your comment seemed to imply that you would normally only polish or refactor code at one point in the SDLC. This I don’t agree with. I believe that you should always polish code after working on it. Refactoring or cleaning up code before you start working on it is optional, but certainly doing both can make sense. So perhaps the key point of disagreement is “how often” instead of “when” :)

The key point of disagreement appears to be “when.” Some say: do it before first release, some say do it as a second pass, still other say to ‘polish’ old code before you work on it, so that you know what you have.

Have you thought about the variations in “when” to polish the code between various SDLC processes?

Keeping the code clear and polished helps reading, analyzing, maintaining, debugging and version controlling.
But be careful when you refactor your code: every change can introduce new bugs. Try to make frequent but small changes, and cover your code with unit testing to make changes safer…

Your list of problems is very helful. Recently, while polishing the code, I have found that one of my method does two different things at a time. Even the method is not long (about 15 lines). I have refactored it and created 2 methods. So I want to add the rule “violation of the principle Single Responsibility” to the list.

After testing and (quickly) polishing my code, I like to take a break, do other thing within 1 or 2 days and then return to my code for a thorough polishing. With this method, I can have a new look at my code (It’s sad to avow that in my company, noone care about the quality of code, there is even no comment at all – so I do this work really for myself)