Date: Thu, 1 Jul 1999 15:24:00 -0400 From: Tim Vanderhoek <vanderh@ecf.utoronto.ca> To: Doug <Doug@gorean.org> Cc: freebsd-ports@FreeBSD.org, nik@nothing-going-on.demon.co.uk Subject: Re: ports/12463: Update: Fvwm2 to 2.2.2 Message-ID: <19990701152359.C48778@mad> In-Reply-To: <Pine.BSF.4.05.9907011108370.12355-100000@dt054n86.san.rr.com>; from Doug on Thu, Jul 01, 1999 at 02:09:22PM -0400 References: <199907010500.WAA19929@freefall.freebsd.org> <Pine.BSF.4.05.9907011108370.12355-100000@dt054n86.san.rr.com>
next in thread | previous in thread | raw e-mail | index | archive | help
[I've Cc'd Nik on this since he's not subscribed to -ports, but he's the -doc guy and may have some brilliant insights :-]. On Thu, Jul 01, 1999 at 02:09:22PM -0400, Doug wrote: > > > The "A " seems to add very little to the comment. > > It adds nothing to the comment, but it does add a great deal of > readability for just two characters. My vote == bad idea. Are you reading it in context, or are you just reading the comment? Try having a look through one of the categories at http://www.FreeBSD.org/ports/. It's not so bad now because a lot of the ports don't include a preceeding "A" or similar, but notice that reading them quickly becomes annoying (not at first, though). For example, [104]xephem-3.2.2 An interactive astronomical ephemeris program [2]ephem-4.28 An interactive terminal-based astronomical ephemeris program [2]WSoundPrefs-1.0.2 A utility for configuring sounds to play for Window Maker events [21]ascd-0.12.1 A dockable cd player for AfterStep or WindowMaker [46]cdd-1.0 A cd audio track extraction program from Charles Henrich [528]oneko-1.2 A cat chasing a mouse all over the screen And notice that it's possible to add "A " to a _lot_ of the comments that currently don't have it, using the same argument that use just used. Now, for some of the comments the "A " is needed. For example, the following could be confusing without "A ", [70]wmspaceweather-1.04 A DockApp that shows the weather at geosynchronous orbit [351]ja-nethack-1.0.5.19970924 A dungeon explorin', slashin', hackin' game [504]nethack-3.2.2 A dungeon explorin', slashin', hackin' game [Notice that in the first, the word "that" would be a good tip-off for an automated program to leave this comment alone]. But, read the comments in the games category. Notice that it's possible to add "A " in front of virtually every comment. Every comment. I'm not convinced that doing so would increase the readability one bit. The ideal pkg/COMMENT, I think, is a type of verb phrase, in the imperitive. [462]luna-1.9 Display her phase [585]unclutter-8 Remove idle cursor image from screen [1396]wget-1.5.3 Retrieve files from the 'net via HTTP and FTP [612]viz-1.1.1 Convert invisible (binary) characters to a visible form [40]bounce-1.0 Bounce tcp connections to another machine/port As an example of a verb phrase using the wrong tense, [1290]tcplist-2.2 Lists tcp connections to/from the local machine (+username on both sides) But it's sometimes hard to write a COMMENT like this, and the vast majority of comments are simply noun phrases, sometimes preceeded by "A ". [1389]web500gw-2.1b2 HTTP gateway to LDAP-based directories [2]SSLtelnet-0.13 SSL enhanced telnet/telnetd [45]bro-0.5a System for detecting Network Intruders in real-time [50]bugs-1.8.1 Great cryptography library and sample programs The vast, _vast_ majority of comments are just nouns of this form. Consider that it is possible to add "A " or "The " to each single one of them. This comes pretty close to simply prepending "A " in front of every pkg/COMMENT. And, of course, some comments are just useless. :) [2]Motif-2.1.10 Motif I'm willing to accept that I'm just unusual with respect to really detesting all the "A "s, but you've got to work a little harder than that to convince me. I'm also considering that maybe I should've made an exception and not capitalized "perl5" when it appears at the start of a comment. -- This is my .signature which gets appended to the end of my messages. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-ports" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990701152359.C48778>