code comments
Last modified on April 06, 2022

Comments don’t change the functionality of the program, but completely changes the user experience of reading someone else’s code. It’s the difference between watching ESPN on mute and watching with the color commentator– you get all the finer points, all the thoughts, all the ramblings connected to this large body of cold, unyielding computer instructions.

For example, here’s some code from my Emacs config:

(setq org-refile-use-cache t) ;;speeds up loading refile targets
(setq org-refile-targets '((nil :maxlevel . 9) ;; at most can refile 9 levels deep in the hierarchy
                           (org-agenda-files :maxlevel . 9)))
(setq org-refile-allow-creating-parent-nodes 'confirm) ;; confirm creation of new nodes as refile targets
(setq org-refile-use-outline-path 'file) ;;see whole hierarchy (not just headline) when refiling
(setq org-outline-path-complete-in-steps nil) ;;easy to complete in one go w/ helm

If I just had the bare config, it’d be pretty opaque what the code means in some cases (e.g., what org-refile-use-outline-path means isn’t super apparent just from the variable name) but also why I’ve set certain settings.

We might need to extend our idea of what code comments can even be. Omar Rizwan has some pretty fascinating ideas on this.

need to be able to put screenshots and video clips of bugs inside my code comments

— Omar Rizwan (@rsnous) November 8, 2021

need to be able to hyperlink other source code files inside comments

— Omar Rizwan (@rsnous) August 16, 2021