From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.devel Subject: RE: changing function signatures and no library version # => must use too-general test Date: Tue, 25 Apr 2006 23:21:55 -0700 Message-ID: References: <878xptaqhs.fsf-monnier+emacs@gnu.org> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1146032556 32626 80.91.229.2 (26 Apr 2006 06:22:36 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Wed, 26 Apr 2006 06:22:36 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Apr 26 08:22:26 2006 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1FYdPo-0006zk-Ui for ged-emacs-devel@m.gmane.org; Wed, 26 Apr 2006 08:22:21 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FYdPo-0006aa-AA for ged-emacs-devel@m.gmane.org; Wed, 26 Apr 2006 02:22:20 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1FYdPY-0006YR-Hv for emacs-devel@gnu.org; Wed, 26 Apr 2006 02:22:04 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1FYdPV-0006Y7-LO for emacs-devel@gnu.org; Wed, 26 Apr 2006 02:22:04 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FYdPV-0006Y4-FI for emacs-devel@gnu.org; Wed, 26 Apr 2006 02:22:01 -0400 Original-Received: from [141.146.126.228] (helo=agminet01.oracle.com) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_3DES_EDE_CBC_SHA:24) (Exim 4.52) id 1FYdS8-0004Km-8V for emacs-devel@gnu.org; Wed, 26 Apr 2006 02:24:44 -0400 Original-Received: from rgmsgw300.us.oracle.com (rgmsgw300.us.oracle.com [138.1.186.49]) by agminet01.oracle.com (Switch-3.1.7/Switch-3.1.7) with ESMTP id k3Q6LxYh005338 for ; Wed, 26 Apr 2006 01:22:00 -0500 Original-Received: from dradamslap (dhcp-amer-csvpn-gw2-141-144-74-251.vpn.oracle.com [141.144.74.251]) by rgmsgw300.us.oracle.com (Switch-3.1.7/Switch-3.1.7) with SMTP id k3Q6LwG5020886 (version=TLSv1/SSLv3 cipher=RC4-MD5 bits=128 verify=NO) for ; Wed, 26 Apr 2006 00:21:59 -0600 Original-To: "Emacs-Devel" X-Priority: 3 (Normal) X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook IMO, Build 9.0.6604 (9.0.2911.0) In-Reply-To: <878xptaqhs.fsf-monnier+emacs@gnu.org> X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2800.1807 Importance: Normal X-Brightmail-Tracker: AAAAAQAAAAI= X-Brightmail-Tracker: AAAAAQAAAAI= X-Whitelist: TRUE X-Whitelist: TRUE X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:53447 Archived-At: > I don't know specifically what happened with > help-insert-xref-button, > but it's prety common to change a function's list of > arguments without > subsantially changing its body and/or its conceptual > meaning, in which > case it will usually makes more sense to keep the same name. > Too bad for Emacs users. No, I don't see how that usually > makes more sense, whether it is common or not. In most coding practices, there is this thing about choosing your function names based on what they do. A good, general rule. > Annoyance to developers is important, but it is not as > important as clean > software and clear software maintenance. It is *specifically* for clarity of the code and clear software maintenance that function names should be chosen correctly, without having to worry about previously used names. Do I detect a little mauvais foi, or do you really believe that is what this is about? 1. You won't find an argument against that from me, at that level of abstraction. As you know, I've argued long and hard for getting function names to accurately reflect what the functions do. Think back to the discussion of the myriad different names for exiting view mode, none of which were very "parlant". Likewise, menu names... 2. However, your argument is at too high an abstraction level. There is not one, single, acceptable name for a given function. For the example given, `help-insert-xref-button', there are plenty of acceptable alternatives, even given the constraints of starting with "help" and including "xref-button": `help-xref-button-insert', `help-insert-an-xref-button', `help-add-xref-button', and so on. 3. Your abstract argument is also presented in stark isolation. It is inappropriate to consider only one (good, general) software-engineering rule (heuristic) and elevate it to the status of something inviolable. Such rules need to be applied, and their application judged appropriate or not, together, in combination, in a particular concrete context. The guidelines I discussed are also important. In a concrete, practical context there are tradeoffs to consider - for example, is it more important that the name be exactly `href-insert-xref-button' (because it accurately describes the function) or is it more important to use a different name because that name is already used for something different (in another Emacs version that is likely to still be in use). Emacs developers might never get confused or bothered by the existence of two different `href-insert-xref-button' functions because they generally work with only one Emacs version, but others who work with multiple versions will. When you add "without having to worry about previously used names", you violate the utility of the good guideline you promote. It's about balancing such general rules, in context, together. It's not about promoting one's favorite rule du jour and trying to sneak in an addendum that it is inviolate even in the face of another rule (in all contexts, no less). Of course names should be as accurate as possible, but yes, we do have to worry also about previously used names much of the time. Legacy is something that software engineering rules need to deal with. Only one-off school projects can ignore legacy (there is none). It's ugly and mundane, no doubt, but it's also part of what makes software development interesting. 4. Also to be measured in such a combined judgement are mitigating factors: A function name is one way to document a function's meaning or behavior, but it is not the only way; a function name that does not communicate sufficiently accurately what the function is about can be supplemented by documentation (the manual), a doc string, and source-code comments.