How to keep comments on variables set through "M-x customize" on emacs?

Question

When I set variables through M-x customize, the values are stored in this big, auto-generated, alphabetically ordered list in my .emacs file.

The problem is I like to document why I chose a particular value other than the default for a particular variable. If I do that by adding elisp comments inside the auto-generated list, they are clobbered next time I customize another variable.

Is there a way to make Custom keep my comments, or is there some other standard way of annotating this?

Answer 1

Personally, I moved all of my settings out of customize and into my .emacs file. Mostly because I really dislike the UI for customize.

So, instead of this is my custom file:

(custom-set-variables
  ;; custom-set-variables was added by Custom.
  ;; If you edit it by hand, you could mess it up, so be careful.
  ;; Your init file should contain only one such instance.
  ;; If there is more than one, they won't work right.
 '(scheme-program-name "scheme")
 '(tetris-use-glyphs nil))

I have:

 (setq
  scheme-program-name "scheme"      ; because I like it
  tetris-use-glyphs nil)            ; it's an example

That being said custom-set-variable does take a number of arguments, one of which is a comment. So you could do:

(custom-set-variables
  ;; custom-set-variables was added by Custom.
  ;; If you edit it by hand, you could mess it up, so be careful.
  ;; Your init file should contain only one such instance.
  ;; If there is more than one, they won't work right.
 '(scheme-program-name "scheme" nil nil "this is a comment")
 '(tetris-use-glyphs nil nil nil "This is another comment"))

The comment will only get blown away when you change the value of the variable, not when you change other variables. I'm not sure that this is the proper usage for this though. C-h f custom-set-variables has more info.

Answer 2

At least since 22.3, you can include a comment when you customize something. Click "State" -> "Add comment". This is saved in the customization commands in your .emacs:

'(global-hi-lock-mode t nil nil "Yes! Yes yes yes yes YES!")

(Apparently I was excited when I found that customization.)