Some classes of comments are pretty had to replace with self-explanatory code: historical, design decisions and negative things. // This code uses FOO because

Some classes of comments are pretty had to replace with self-explanatory code: historical, design decisions and negative things. // This code uses FOO because when it was originally written, we expected to process millions of items, so fast random access time was important. This is no longer the case -- feel free to refactor to use BAR instead. // Do not refactor this code to use BAR! While this will make the function shorter, the result will have O(n^3) complexity, and this function may get millions of input items in some cases.