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

Sat Feb 25 00:16:59 GMT 2012

Dear Jakob,

Just a small remark. Rereading the conversation I noticed that you
changed your position from a particular case to a general one.
Originally you seemed to have problem with the "IsRat" name,
presumably because of being vague about its meaning as it could refer
to a not so popular rodent. But now you are sort of suggesting large
scale changes in the GAP coding conventions.

I see your point and I would happy to see the results of you
experiment. As a software developer myself I have to deal with these
problems every day. In this particular case of  GAP and these short
names I would definitely vote for GAP's current approach. In a
computer algebra context I see no possibility of misunderstanding
'IsRat', as opposed to a Zoo management software. On the other hand
code lines are shorter which is another big factor in readability.  Of
course, I would like to emphasize, that this is only my personal
opinion.

best wishes,
attila

On Sat, Feb 25, 2012 at 10:34 AM, kroeker <kroeker at uni-math.gwdg.de> 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
>>>
>>> _______________________________________________
>>> Forum mailing list
>>> Forum at mail.gap-system.org
>>> http://mail.gap-system.org/mailman/listinfo/forum
>>
>>
>> --
>> Dr. Alexander Konovalov               School of Computer Science
>> &  Centre for Interdisciplinary Research in Computational Algebra
>> University of St Andrews                 Tel +44/0 (1334) 461633
>> http://www.cs.st-andrews.ac.uk/~alexk    Fax +44/0 (1334) 463278
>> The University of St Andrews is a charity registered in
>> Scotland:No.SC013532
>>
>>
>>
>>
>>
>>
>>
>
>
> _______________________________________________
> Forum mailing list
> Forum at mail.gap-system.org
> http://mail.gap-system.org/mailman/listinfo/forum