When writing comments in my code, I sometimes use HACK, TODO and NOTE keywords to mark that comment as especially important. I can easily search for these keywords to find the comments and review the code.
HACK: Used for sections that are not obvious/easy to understand. Worse, one might misunderstand and try to change the code.
Examples:
/* HACK: Do scrolling back and forth so that active tab will be visible even when the there are multiple tabs and the active tab does not fit pane. This happens after the fourth tab, i.e. the 5th tab is created and selected but is not visible on frame. Worse, the right arrow of tabbed pane is disabled. I only could come up with this hack to solve it. There must be a better solution... */
/* HACK: Analyze stack trace to check if call was due to mouseRelease because we need to ignore the other calls due to mouse press and click to prevent adding the same point twice. */
TODO: Used for remaining work.
Examples:
//TODO: When is this called? I could not get here by closing the window.
//TODO this calculation has to be updated when user changes height.
//TODO: To have correct normals, vertex orders have to be the same. It will show its effect when CULL_ is selected.
//TODO: Add reference.
//TODO: Enable this try-catch when color problem is resolved.
//TODO: Should we also issue an error message?
//TODO This method similar (same?) to the method in Sphere.
//TODO Review this validity check.
//TODO : Due to a bug, it starts from t = 1 second.
NOTE: I add this keyword to sections where in the past I changed the code to a seemingly better form and failed because I did not think about some edge cases. The next time I am tempted to change the code, I read the comment and think twice.
Examples:
//Note: You cannot use showException() here because that would cause recursive calls and lead to stack overflow.
//Note: We cannot load the same dll two times in a row, even after garbage collection. But we can load it after a different one has been loaded.
//Note: In order the use invokeLater here, the whole GUI creation process has to be refactored, i.e. couple of days work.
//NOTE: We had to use JButton instead of JLabel because only JLabel does not gain focus while JButton can.
//Note: mousePressed is more responsive than mouseClicked.
//NOTE: Do not perform lengthy operations (e.g. setting font to bold) inside this paint method because it causes 100% CPU load.
//Note: Math.IEEEremainder(10.04, 10) = 0.03999999999999915
/* NOTE: Due to precision limitation (15 digits after decimal point) of double, Long.MAX_VALUE + 1024.0 is the same as Long.MAX_VALUE. Only after +1025.0 are we able to see a difference. double d = Long.MAX_VALUE results in a double value of 9.223372036854776E18 although Long.MAX_VALUE = 9223372036854775807 = 9.223372036854775807E18. The last three digits (807) are lost due to rounding during double conversion. Same is true for lower bound. */
