better comments to sync with diagram