bug#22019: 25.0.50; Bad comment in `character-fold-to-regexp'

bug#22019: 25.0.50; Bad comment in `character-fold-to-regexp'

[Drew Adams]

This part of an explanatory comment is inadequate and inappropriate:

 ;; See commit message for a longer description.

What commit message?  The source code should contain the description.
If a VC commit message happens to also contain the description, so
much the better for it.  But that doesn't help a reader of the code.

This comment is intended to make clear what the design/intention is.
Readers of the source code deserve the additional design information
as much as maintainers who might bother to access the relevant commit.


In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2015-11-12
Bzr revision: 6e5186e8a7ccfb9b8fb35b5f4f0371e4f4a68162
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/snapshot/trunk
 --enable-checking=yes,glyphs --enable-check-lisp-object-type
 --without-compress-install --with-wide-int 'CFLAGS=-O0 -ggdb3'
 LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

bug#22019: 25.0.50; Bad comment in `character-fold-to-regexp'

[Artur Malabarba]

[-- Attachment #1: Type: text/plain, Size: 682 bytes --]

On 26 Nov 2015 11:03 pm, "Drew Adams" <drew.adams@oracle.com> wrote:
>
> This part of an explanatory comment is inadequate and inappropriate:
>
>  ;; See commit message for a longer description.
>
> What commit message?  The source code should contain the description.
> If a VC commit message happens to also contain the description, so
> much the better for it.  But that doesn't help a reader of the code.

Maybe I'm just a little too acostumed to the convenience of magit-blame.
Commit messages are the first place I look when I don't understand the
code. But I understand that doesn't help readers who are not reading
directly from the repo, so a better comment would be nice.

[-- Attachment #2: Type: text/html, Size: 866 bytes --]

bug#22019: 25.0.50; Bad comment in `character-fold-to-regexp'

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > This part of an explanatory comment is inadequate and inappropriate:

  >  ;; See commit message for a longer description.

That's right.  GNU standard practices say the place to put
an explanation is in a comment, not in a change log.

Can someone please fix this one now?  We shouldn't leave this
dirty in the sink overnight.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

bug#22019: 25.0.50; Bad comment in `character-fold-to-regexp'

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Fri, 27 Nov 2015 01:38:33 -0500
> Cc: 22019@debbugs.gnu.org
> 
>   > This part of an explanatory comment is inadequate and inappropriate:
> 
>   >  ;; See commit message for a longer description.
> 
> That's right.  GNU standard practices say the place to put
> an explanation is in a comment, not in a change log.
> 
> Can someone please fix this one now?

Done.