better documentation of heuristics