RE: building gmp-3.1.1 on darwin...

[David T. Ashley]

OK, for my laziness, I will put my replies in ALL CAPS.

-----Original Message-----
From: Hans Aberg [mailto:address@hidden
Sent: Sunday, August 05, 2001 6:08 AM
To: David T. Ashley
Cc: Torbjorn Granlund; address@hidden
Subject: RE: building gmp-3.1.1 on darwin...


At 17:33 -0400 2001/08/04, David T. Ashley wrote:
>The serious point is that the GMP MP library is technically outstanding but
>does not meet universally accepted coding standards for the C programming
>language.

I will just give my own personal impressions (as a user, I am myself not a
part of the GMP project):

>a)The use of TAB characters, which is discouraged in over 1/2 of coding
>standards.

I have used a number of variations over the last years: UNIX systems always
sets tabs to 8 spaces, it seems, but on MacOS, I have used 4. On UNIX
systems, some use hybrids, every second a tab equivalent to 8 spaces, and
every second four spaces, as to emulated tabs on 4 spaces. This screws up
platform porting.

So eventually, I ended up with just using two spaces instead of a tab,
which is easy enough to type by hand. For readability, one does not need
more than two spaces on each tab, it turns out. Others seem to use this
too, for example the GNU Bison project.

THE REASON THAT TAB CHARACTERS ARE DISCOURAGED BY MANY CODING STANDARDS
ISN'T BECAUSE THEY INTERFERE WITH A COMPILER OR DEVELOPMENT TOOLS--THEY
NEVER DO.  THEY TEND TO INTERFERE WITH EDITORS, WHICH TREAT THEM
INCONSISTENTLY, AND PRINTING, BECAUSE SOMETIMES PRINTERS TREAT THEM
DIFFERENTLY, TOO.  MOST EDITORS HAVE AN OPTION TO USE SPACES RATHER THAN
TABS AND ALSO MOST EDITORS WHEN PRINTING ARE SMART ENOUGH NEVER TO SEND TAB
CHARACTERS TO THE PRINTER.  FORTUNATELY  MANY EDITORS HAVE A C-FORMATTING
FEATURE WHERE IF C CODE IS WEIRD YOU CAN REALIGN IT.  TABS ARE MOSTLY AN
ANNOYANCE ISSUE.  ALSO, EVEN IF THE EDITOR SHIELDS THE PRINTER FROM TABS,
SOME PEOPLE STILL MIGHT DO A:

COPY MYFILE.C LPT1:

WHICH IS OFTEN A FORMATTING DISASTER.

THE WORST CASE, OF COURSE, IS WHEN THE EDITOR TREATS A TAB AS 3 SPACES AND
THE PRINTER 8.  OR, WHEN A SOURCE FILE USES A MIXTURE OF TABS AND SPACES TO
GAIN ALIGNMENT--THE CODE VIEWS JUST RIGHT ON THE EDITOR BUT GOES TO HELL ON
A DIFFERENT EDITOR OR WHEN SENT TO THE PRINTER.

ULTIMATELY, IT IS A STRONG CONVENIENCE ISSUE.  TABS NEVER BREAK COMPILERS.

SEE:

http://www.possibility.com/Cpp/CppCodingStandard.html#indent

http://www.econos.de/delphi/cs.html

Indentation
Indenting will be two spaces per level. Do not save tab characters to source
files. The reason for this is because tab characters are expanded to
different widths with different users settings and by different source
management utilities (print, archive, version control, etc.).

You can disable saving tab characters by turning off the "Use tab character"
and "Optimal fill" check boxes on the Editor page of the Environment Options
dialog (accessed via Tools | Environment).

AND SO ON ...


>b)The inconsistent naming conventions, which could lead to a name clash if
>the source code is used in a larger project.

What problems do you have in your mind here?

EVEN THOUGH IT IS INCONVENIENT, ONE COMMON PRACTICE IS TO PREFIX EVERYTHING
WITH WITH THE NAME OF THE FILE.  FOR EXAMPLE, WHEN I REDID THE GMP LIBRARY,
THE FILES ARE GMP_INTS.C AND GMP_INTS.H.  SO, I HAVE NAMES LIKE:

GMP_INTS_mpz_mul()
GMP_INTS_KARABATSU_THRESHOLD

(Hope I spelled that guy's name right--that has always been a mental block
for me.)

THE ISSUE IS THAT ANY NAMES MIGHT COLLIDE WITH NAMES IN OTHER SOURCE
MODULES.  BUT WITH THE GMP LIBRARY, THIS SEEMS UNLIKELY, AS THE "mpz" AND
OTHER COMPONENTS IN FUNCTION NAMES WOULD BE PRETTY RARE.  ANYWAY, EVERYTHING
PUBLIC IN THE "H" FILE SHOULD BE DECISIVELY NAMED SO IT WON'T COLLIDE WITH
MACROS OR CONSTANTS IN OTHER SOURCE FILES IN WHICH THE .H FILE IS INCLUDED.

SOME CODING STANDARDS RECOMMEND THE AGGRESSIVE STYLE ABOVE SO THAT NAME
CLASHES ARE IMPOSSIBLE.  IN OTHER WORDS, IF YOU HAVE DIFFERENT FILE NAMES,
ALL IDENTIFIER NAMES WILL BE DIFFERENT, TOO.

>c)The lack of documentation in the code.  It is spotty.  In some places, it
>is outstanding, but in other places it is lacking.

I think this is inevitable, as this kind of source code documentation takes
time, and people that write this kind of code tend to learn how to read the
code itself.

I AGREE TO SOME EXTENT.

>d)The sheer number of source files involved.

I think this is a platform issue: For example, under MacOS pre-X, it was
preferable with a low number of files, as the disk operating system could
not handle well many small files (a hard disk sector could not have more
than one file). However, under UNIX, the file is a basic unit in an
entirely different way. So in fact, under MacOS X, which has Mach-kernel
based BSD, the old multi-component files are split into different files,
and the use of many files is encouraged (with respect to the file resource
components).

FOR ME, I TOOK A NON-STANDARD PATH TO USING THE LIBRARY--I EDITED THINGS
MANUALLY AND BROUGHT THEM INTO A MSVC++ PROJECT.  I'M JUST WHINING BECAUSE
IT WAS HARD FOR ME.

>f)The inconsistent trapping at the interfaces.  (As I ported the code, I
had
>to add a great number of assert() statements to trap suspicious things at
>function interfaces.)

Would mind giving some examples?

SURE.  BY INTERFACE I MEAN FUNCTION INTERFACE.  SO, LET'S USE THE
mpz_mul(result, arg1, arg2) FUNCTION AS AN EXAMPLE.  ALSO KEEP IN MIND I
RENAMED STRUCTURE MEMBER NAMES AS WELL SO MY NAMES WILL BE DIFFERENT.

HERE IS THE FIRST PART OF THIS FUNCTION:

void GMP_INTS_mpz_mul (      GMP_INTS_mpz_struct *w,
                       const GMP_INTS_mpz_struct *u,
                       const GMP_INTS_mpz_struct *v)
   {
   GMP_INTS_size_t    usize = u->size;
   GMP_INTS_size_t    vsize = v->size;
   GMP_INTS_size_t    wsize;
   GMP_INTS_size_t    sign_product;
   GMP_INTS_limb_ptr  up, vp;
   GMP_INTS_limb_ptr  wp;
   GMP_INTS_limb_ptr  free_me = NULL;
   GMP_INTS_size_t    free_me_size;
   GMP_INTS_limb_t    cy_limb;

   //Eyeball the inputs.
   assert(w != NULL);
   assert(w->n_allocd > 0);
   assert(w->limbs != NULL);
   assert(u != NULL);
   assert(u->n_allocd > 0);
   assert(u->limbs != NULL);
   assert(v != NULL);
   assert(v->n_allocd > 0);
   assert(v->limbs != NULL);

ANYWAY, ASSERTS ARE KIND OF A FREEBIE, BECAUSE THEY GET COMPILED OUT UNLESS
IN DEBUG MODE.  SO IT IS STANDARD PRACTICE TO TRAP THE INTERFACES IN THIS
WAY.  EVERYTHING THAT CAN BE DETECTED WITH FUNCTION PARAMETERS SHOULD BE
TRAPPED.  THIS ACTUALLY SAVED ME ONCE WHEN I FORGOT TO INITIALIZE AN
INTEGER.  BUT, OF COURSE, DYNAMIC ALLOCATION ERRORS ARE SO CATASTROPHIC ON A
MACHINE WITH MEMORY MANAGEMENT THAT PROBABLY EVEN WITHOUT THE ASSERT THE
FIRST POINTER DEREFERENCE WOULD HAVE MADE NOISE.

KEEP IN MIND THAT MY COMMENTS ARE A MIXTURE OF TRUTH AND ANAL-RETENTIVENESS.
SO ... IT AIN'T ABSOLUTE TRUTH.

BEST REGARDS, DAVE.


  Hans Aberg