[GAP Forum] "IsRationalNumber" as synonym for "IsRat"

[Alexander Konovalov]

Dear Jakob,

I regret to decline your proposal, since I have other priorities in my 
contributions to the development of the GAP system, and there is no my 
time available to continue this discussion on synonyms, an opinion on 
which I've already expressed. 

Nevertheless, please be sure that suggestions expressed in the GAP 
Forum are heard by GAP developers, and those which will be considered 
to be reasonable may be added to our TODO lists (however, with various 
priorities). 

On the other hand, replying to your recent mail to GAP Support, I've
outlined other topics which I would be more interested to discuss in 
the context of your work, namely, GAP package development and 
interfacing GAP and Macaulay2 using SCSCP. If you will have any 
questions about these topics, please let me know.

Best regards,
Alexander


On 24 Feb 2012, at 23:34, kroeker wrote:

> Dear Alexander,
> 
> 
> I suppose I cannot convince you via conventional arguing, that it is invaluable to use descriptive names
> like "IsRationalNumber". I think even citing papers from software engineering researchers may not help.
> 
> 
> Therefore I suggest following experiment:
> 
> 1. choose a small piece of GAP code with moderate or extensive use of short variable names
> e.g. `IsInt', `IsPosInt', `IsCyc' 'isRat'.
> 
> 2. Send me this piece of code and I will suggest more descriptive names.
> 
> 3. copy a bunch of the printouts with the original code and the modified version.
> 
> 4. -distribute the printouts among your friends and ask them which version they mostly like or
> -distribute the printouts among several GAP developers and ask them which printout version is more readable.
> 
> Independently of the result I will invite you for lunch if you accomplish this experiment. Do you accept?
> 
> 
> Best regards,
> 
> 
> Jakob
> 
> 
> P.S. if somebody ever had to maintain or review third party source code, he will probably know
> the importance of code readability. Speaking names also reduces the barrier to learn a new
> (CAS) language.
> 
> 
> Am 23.02.2012 21:39, schrieb Alexander Konovalov:
>> Dear Jakob,
>> 
>> On 23 Feb 2012, at 13:55, kroeker wrote:
>> 
>>> Dear Alexander, dear GAP forum,
>>> 
>>> 
>>> it is ok to have short names but also consider that in software engineering  it is known
>>> that variable and function names should  be as descriptive as possible
>>> (and at the same time not too long of course).
>> In this case then 'IsPosRat' is certainly more descriptive than 'IsPR',
>> and, moreover, it naturally follows GAP naming conventions for some
>> central categories of objects.
>> 
>>> My intention is not to customize my personal use but to improve the usability and code readability for everybody.
>>> So I can't see any serious arguments against introducing the synonym "IsRationalNumber" for now.
>> There is a guidance in the GAP manual about using synonyms, which says:
>> 
>> ----
>> Two typical intended usages are to declare an "and-filter", e.g.
>> 
>> DeclareSynonym( "IsGroup", IsMagmaWithInverses and IsAssociative );
>> 
>> and to provide a previously declared global function with an alternative name, e.g.
>> 
>> DeclareGlobalFunction( "SizeOfSomething" );
>> DeclareSynonym( "OrderOfSomething", SizeOfSomething );
>> 
>> Note: Before using DeclareSynonym in the way of this second example, one should
>> determine whether the synonym is really needed. Perhaps an extra index entry in
>> the documentation would be sufficient.
>> ----
>> 
>> From this, I don't think that there are any serious arguments in favour of the
>> synonym IsRationalNumber for IsRat. It's really easy to find the meaning of
>> IsRat using the help system, and if one searches for rationals in the
>> documentation, then IsRat comes in the next manual section. You may grep the
>> GAP library code to see actual examples when it is used in the library - in
>> most cases there are much more grounds to introduce synonyms there.
>> 
>> Best,
>> Alexander
>> 
>>> Am 22.02.2012 23:13, schrieb Alexander Konovalov:
>>>> Dear Jakob, dear GAP Forum,
>>>> 
>>>> On 21 Feb 2012, at 19:04, kroeker wrote:
>>>> 
>>>>> Dear GAP-developers,
>>>>> 
>>>>> I do not really like the function name  "IsRat" for the check if an object is a rational number
>>>>> and suggest to introduce the synonym "IsRationalNumber" :
>>>>>  DeclareSynonym("IsRationalNumber",IsRat);
>>>>> 
>>>>> What is your opinion?
>>>>> 
>>>>> Jakob
>>>> GAP as a number of short names for such common categories like e.g. `IsInt', `IsPosInt', `IsCyc',
>>>> `IsBool', `IsFFE', `IsChar', `IsPerm' etc., so to my mind `IsRat' fits this naming scheme quite
>>>> well. These are used in many method installations and having compact names is quite handy.
>>>> 
>>>> The page http://www.gap-system.org/Faq/Usage/usage1.html explains how to customise GAP using the
>>>> .gaprc file, so if you prefer this synonym for your personal use, you may add this line there.
>>>> Of course, any code using it will not work without this declaration.
>>>> 
>>>> Best wishes,
>>>> Alexander