I think some comments  / docs about _why_ would be great here for future me when I maintain this code.