Yes, it's particularly difficult recovering from the situation where you were handed poorly-commented code. "Recovering" is about all you can do, retroactively. The solution is in working proactively when you get the chance to mold the minds of your successors.

I try to instill the following principle in new developers:

Put strategy in comments, tactics in code.

Another way to phrase this, though I think it's less strong, is "Comment why, code how." Comments should be an orientation to the general approach, not a roadmap to the use of the language and techniques used. Comments are for the maintenance programmer, who really doesn't want to STUDY your code, just surgically adjust it.

Enforcing the strategy/tactics metaphor also implies that you have to have a strategy before you can employ effective tactics. For a largish subroutine, start by coding the stub, with an English explanation of the approach to be taken. Under each line of comment, execute the tactics that will meet the strategy. Under "# Arrange unique entries", write the hash scanning and schwartian transform that achieves this aim.

Lastly, try to phrase your code so that it reads. One trick is to imagine trying to read your code aloud over the phone to someone else. Don't worry about using a few extra lines instead of a few extra clever operators. Don't hide the key conditionals that will control the routine. Be clear.

--
[ e d @ h a l l e y . c c ]