follow Julien's comments and update codebase