add comments and improve exceptions