ketan agrawal

code comments
Last modified on April 06, 2022

Why do we comment our programs?

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.

What could be in store for the future of code comments?

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

Links to “code comments”

Taking notes is good.

Documentation when programming is good. It makes the user experience better - connection to HCI stuff.

Come to think of it… code comments are essentially just notes about code, intermingled with that code itself.