Comments are good, this particular instance, not so much. This description spends a lot of time stating the blindingly obvious, eg: if (addedFiles.length

Comments are good, this particular instance, not so much. This description spends a lot of time stating the blindingly obvious, eg: if (addedFiles.length === 0) { // Abort if no files matched path. throw new Error(files.pathFromRepoRoot(path) + " did not match any files"); Or: // If --bare was passed, write to the Git config indicating that the repository is bare. // If --bare was not passed, write to the Git config saying the repository is not bare. config: config.objToStr({ core: { "": { bare: opts.bare === true }}}), This really adds no information if the names are clear and you can read JS. The important thing isn't what is happening in the code, because you already can see that in the code. It's WHY. For instance, it'd be far more useful to explain what is a 'bare repository', what are the implications of it, and why are we keeping track of that data, than to say "If it's bare, we write in the file that it's bare". I feel that explaining TLS and similar in this manner would be completely unhelpful. Check out this document, for instance, specifically the "Algorithm for crypt" part: https://www.akkadia.org/drepper/SHA-crypt.txt https://www.akkadia.org/drepper/SHA-crypt.txt Very well explained. But try and tell me what's the purpose and why those specific steps, which look increasingly bizarre as you delve in, and whether deviating from any given step would be acceptable or not (ignoring matters of compatibility)