[californiaguy]

> Add comments in the doc string or anywhere, that say, this is "magic", or "bad" and needs to be rewritten.

These are XXX comments and they're pretty common even with the best developers. They're so common that pretty much every editor has a syntax highlighting regex to detect them.

[cturner]

I'd go further - it's a good thing to do. It allows you to cruise through and get your main algorithm going, and then focus on details when you can afford for your brain to be doing that. I used to get distracted by this stuff and then forget about the big picture thing I was doing. Sometimes you can eve stub out lists of things with these as comments and then fill in the gaps as you're able to. Sometimes I review and realise the initial idea was too complicated and that I've saved energy.

[abstractbill]

Yup, they're common, and I agree with cturner - they're a very good thing. Comments that point out bad sections of code that need rewriting are invaluable.