Dear Attila,
> In this particular case of GAP and these short
> names I would definitely vote for GAP's current approach.
It is also possible (just a hypothesis) that you got adopted to variable
and function names in GAP
and the same will happen to me and to other GAP users and that after
the adoption process
shorter lines are the bigger factor in relation to less-descriptive names.
Let me here remark that a lot of coding conventions and techniques are
just implications from
basic principles like 'locality', 're-usability', 'correctness' or the
idea that we are writing code
mainly for other people and not for ourselves and so on.
Unfortunately I'm still catching myself too often writing non-optimal
code and
I have to remind myself every day to do it the right way
(applying known facts from operating experience and research), what
sometimes frustrates me.
From the feedback I got until now I conclude that GAP developers have
different positions on the issue of short vs. descriptive names
and I probably should stop the discussion here without suggesting large
changes for now.
One reason is that changes may lead to unforeseeable consequences you
never would think of.
Thank you all for the discussion and happy coding!
Jakob
Am 25.02.2012 01:16, schrieb Attila Egri-Nagy:
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<kroe...@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@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@mail.gap-system.org
http://mail.gap-system.org/mailman/listinfo/forum
_______________________________________________
Forum mailing list
Forum@mail.gap-system.org
http://mail.gap-system.org/mailman/listinfo/forum
