International Components for Unicode

ICU Coding Guidelines

This page describes guidelines for writing code for the International Components for Unicode and how to add it to the project.

• General Guidelines
• Adding files to ICU
• Build Tools

General Guidelines

• Constants (#define, enum items, const): uppercase. UBREAKITERATOR_DONE, UBIDI_DEFAULT_LTR, ULESS.
• Variables and functions: mixed-case, starting with lowercase. getLength().
• Types (class, struct, enum, union): mixed-case, starting with uppercase. class DateFormatSymbols.
• We use getProperty() and setProperty() functions.
• getLength(), getSomethingAt(index/offset).
• Where we return a number of items, it is countItems() - not getItemCount() (even if we do not need to actually count in the implementation of that member function).
• Ranges of indexes: we specify a range of indexes by having start and limit parameters, with names or suffixes like that. Such a range contains indexes from start to limit-1, i.e., it is an interval that is left-closed and right-open. Mathematically, [start..limit[.
• Functions that take a buffer (pointer) and a length argument with a default value so that the function determines the length of the input itself (for text, calling u_strlen()), that default value should be -1. Any other negative or undefined value constitutes an error.
• Primitive types: they are defined by utypes.h or a header file that it includes. The most common ones are uint8_t, uint16_t, uint32_t, int8_t, int16_t, int32_t, UTextOffset (signed), and UErrorCode.
• File names (.h, .c, .cpp, data files, etc.): 8.3, all lowercase.
• Language extensions and standards: do not use any features (language extensions or library functions) that are proprietary and do not work on all C or C++ compilers.
  For example, in Microsoft Visual C++, you should go to Project Settings(alt-f7)->All Configurations->C/C++->Customize, and set Disable Language Extensions.
• Tabs and indentation: no tab characters (\x09), save files with spaces instead.
  Indentation is of size 4.
• Documentation: We use Javadoc-style in-file documentation with doc++. We have a printed version of the manual in our "library", and our files use this.
• You should not place multiple statements into one line. You should not have if() or loop heads followed by their bodies on the same line.
• Placements of curly braces {}: each of us subscribes to different philosophies. Please try to do it reasonably and consistently. It is a good idea to use the style of a file when you modify it, instead of mixing in your favorite style.
  The one thing that we ask for is to not have if() and loop bodies without curly braces.
• Function declarations should have one line with the return type and all the import, extern, and export declarations, and the function name and signature at the beginning of the next line.

  U_CAPI int32_t U_EXPORT2
  u_formatMessage(...);
  

• Error codes: The ICU API functions for both C and C++ are using a pointer or a reference to UErrorCode whereever we expect things to possibly go wrong.

  In C, this is a pointer, and it must be checked for NULL. In C++, this is a reference. In both cases, it must be checked for an error code already being in there:

  U_CAPI const UBiDiLevel * U_EXPORT2
  ubidi_getLevels(UBiDi *pBiDi, UErrorCode *pErrorCode) {
      UTextOffset start, length;
  
      if(pErrorCode==NULL || U_FAILURE(*pErrorCode)) {
          return NULL;
      } else if(pBiDi==NULL || (length=pBiDi->length)<=0) {
          *pErrorCode=U_ILLEGAL_ARGUMENT_ERROR;
          return NULL;
      }
  
      ...
      return result;
  }
  

  This prevents the API function from doing anything on data that is not valid in a chain of function calls and relieves the caller from checking the error code after each call.
• Decide whether your module is part of the "common" or the "i18n" API collection. Use the appropriate macros, like U_COMMON_IMPLEMENTATION, U_I18N_IMPLEMENTATION, U_COMMON_API, U_I18N_API. See utypes.h.
• If we have the same module in C and in C++, then there will be two header files, one for each language, even if one uses the other. For example, ubidi.h for C and bidi.h for C++.

• Platform dependencies are dealt with in the header files that utypes.h includes. They are platform.h and its more specific cousins like pwin32.h for Windows, which define basic types, and putil.h, which defines platform utilities.

  Important: Outside of these files, and a small number of implementation files that depend on platform differences (like umutex.c), no ICU source code may have any #ifdef OperatingSystemName instructions.

• For mutual-exclusion (mutex) blocks, there should be no function calls within a mutex block. The idea behind this is to prevent deadlocks from occuring later. There should be as little code inside a mutex block as possible to minimize the performance degradation from blocked threads.

C Guidelines

• Since we don't have classes to subdivide the namespace, we use prefixes to avoid name collisions. Some of those prefixes contain a 3- (or sometimes 4-) letter module identifier. Very general names like u_charDirection() don't have a module identifier in their prefix.
  • For POSIX replacements, we prepend the (all lowercase) POSIX function name with "u_": u_strlen().
  • For other API functions, we prepend a 'u', the module identifier (if appropriate), and an underscore '_', followed by the mixed-case function name: u_charDirection(), ubidi_setPara().
  • For types (struct, enum, union), we prepend a "U", often "U<module identifier>" directly to the typename, without an underscore. UComparisonResult.
  • For #defined constants and macros , we prepend a "U_", often "U<module identifier>_" with an underscore to the uppercase macro name. U_ZERO_ERROR, U_SUCCESS().
• Function declarations need to be of the form U_CAPI return-type U_EXPORT2 to satisfy all compilers' needs.
• Functions that roughly compare to constructors and destructors are called umod_open() and umod_close().

  U_CAPI UBiDi * U_EXPORT2
  ubidi_open();
  
  U_CAPI UBiDi * U_EXPORT2
  ubidi_openSized(UTextOffset maxLength, UTextOffset maxRunCount);
  
  U_CAPI void U_EXPORT2
  ubidi_close(UBiDi *pBiDi);
  

• In cases like BreakIterator and NumberFormat, instead of having several different 'open' APIs for each kind of instances, use an enum selector.
• File names begin with a "u".
• For memory allocation in C implementation files for ICU, the functions/macros in cmemory.h must be used.

C++ Guidelines

• Classes and their members do not need a "U" or any other prefix.
• class APIs need to be declared like class U_I18N_API SimpleDateFormat or like class U_COMMON_API UCharCharacterIterator.
• Class member functions should be only declared, not inline-implemented, in the class declaration. Inline implementations may follow after the class declaration in the same file.
• We are using XP_PLUSPLUS to make sure the compiler does C++, not __cplusplus.
• We do not use exceptions, and we do not use templates (at least on the API).
• File names do not begin with a "u".

• Adoption of objects:

  Some constructors and factory functions take pointers to objects that they adopt. This means that the newly created object will contain a pointer to the adoptee and takes over ownership and lifecycle control. If an error occurs while creating the new object - and thus in the code that adopts an object - then the semantics used within ICU must be adopt-on-call (as opposed to, e.g., adopt-on-success):
  • General: A constructor or factory function that adopts an object does so in all cases, even if an error occurs and a UErrorCode is set. This means that either the adoptee is deleted immediately or its pointer is stored in the new object. The former case is most common when the constructor or factory function is called and the UErrorCode already indicates a failure. In the latter case, the new object must take care of deleting the adoptee once it is deleted itself regardless of whether the constructor was successful.
  • Constructors: The code that creates the object with the new operator must check the resulting pointer returned by new and delete any adoptees if it is 0 because the constructor was not called. (Typically, a UErrorCode must be set to U_MEMORY_ALLOCATION_ERROR.)
  • Factory functions (createInstance()): The factory function must set a U_MEMORY_ALLOCATION_ERROR and delete any adoptees if it cannot allocate the new object. If the construction of the object fails otherwise, then the factory function must delete it - and it in turn must delete its adoptees. As a result, a factory function always returns either a valid object and a successful UErrorCode, or a 0 pointer and a failure UErrorCode.
    Example:

    Calendar*
    Calendar::createInstance(TimeZone* zone, UErrorCode& errorCode) {
        if(U_FAILURE(errorCode)) {
            delete zone;
            return 0;
        }
        // since the Locale isn't specified, use the default locale
        Calendar* c = new GregorianCalendar(zone, Locale::getDefault(), errorCode);
        if(c == 0) {
            errorCode = U_MEMORY_ALLOCATION_ERROR;
            delete zone;
        } else if(U_FAILURE(errorCode)) {
            delete c;
            c = 0;
        }
        return c;
    }
    

• For memory allocation in C++ implementation files for ICU, the standard new and delete operators (or the C functions/macros in cmemory.h) must be used.

Adding files to ICU

Adding .c, .cpp, and .h files

In order to add compilable files to ICU, you not only need to add them to the source code control system in the appropriate folder, but also add them to the build environment.

The first step is to choose one of the ICU libraries:

1. The common library provides mostly low-level utilities and basic APIs that often do not make use of Locales. Examples are APIs that deal with character properties, the Locale APIs themselves, and ResourceBundle APIs.
2. The i18n library provides Locale-dependent and -using APIs, like for collation and formatting, that are most useful for internationalized user input and output.

Put the source code files into the folder icu/source/library-name.

Then add them to the build system:

• For most platforms, add the expected .o files to icu/source/library-name/Makefile.in, to the OBJECTS variable.

  Add the public header files to the HEADERS variable.

• For Microsoft Visual C++ 6.0, add all the source code files to icu/source/library-name/library-name.dsp. If you don't have Visual C++, then try to add the filenames to the project file manually; it is a text file, and this part should be fairly obvious.

You also need to add test code to icu/source/test/cintltest for C APIs and to icu/source/test/intltest for C++ APIs.

All the API functions must be called by the test code (100% API coverage), and at least 85% of the implementation code should be exercised by the tests (>=85% code coverage).

1. For C, create test code using the log_err(), log_info(), and log_verbose() APIs from cintltst.h (which uses ctest.h), and check it into the appropriate folder.
2. In order to get your C test code called, you have to add its toplevel function and a descriptive test module path to the test system by calling addTest(). The function that makes the call to addTest() ultimately has to be called by addAllTests() in calltest.c. Groups of tests typically have a common addGroup() function that calls addTest() for the test functions in its group, according to the common part of the test module path.
3. Add that test code to the build system, too. Modify Makefile.in and the appropriate .dsp file like for the library code.

Build Tools

We are using the following tools to build ICU:

• GNU make version 3.76.1 and up.
• GNU cc version 2.95.2 and up. (egcs merged back into gcc.)
• autoconf version 2.13 and up.
• autoconf needs m4 version 1.4 and up.
• Platform-specific compilers as listed with the supported platforms.
  (For a complete list of supported platforms, see the ICU Technical FAQ.)
• On Windows: Microsoft Visual C++ 6.0 with the latest Service Packs.