|
From: | Paul Eggert |
Subject: | Re: GnuTLS and zeroing keys in Emacs |
Date: | Sun, 16 Jul 2017 17:29:09 -0700 |
User-agent: | Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.2.1 |
Ted Zlatanov wrote:
PE> - Lisp_Object cp = listn (CONSTYPE_HEAP, 15, PE> - /* A symbol representing the cipher */ PE> - intern (gnutls_cipher_get_name (gca)), You removed the comments from these lists in the C code in several places, but I do think they are useful to a reader. Can we keep them?
I restored those particular comments by installing the attached patch. That being said, I found the comments to have more cost (in terms of clutter) than benefit (in terms of useful information conveyed), and similarly for some nearby comments that I also removed. For example, anyone who reads the Emacs C code should know that "intern (gnutls_cipher_get_name (gca))" returns a symbol representing the cipher name, and the nearby comment "/* A symbol representing the GnuTLS cipher. */" just gets in the way; it has the feel of "n++; /* Increment N. */".
Admittedly this is a judgment call.
PE> -Returns nil on error. PE> +Return nil on error. Is this right? It seems it's talking from the POV of the function.
Doc strings for functions should use the imperative form, as it is typically shorter and less likely to be misunderstood. For example the doc string for the 'length' function begins "Return the length of ...".
0001-src-gnutls.c-Restore-some-comments.patch
Description: Text Data
[Prev in Thread] | Current Thread | [Next in Thread] |