Numbers
This chapter summarizes some of the widely-applicable guidelines for handling numbers in technical context. In financial, marketing and other contexts where the guidelines may not be applicable, editorial judgment must be used to preserve clarity, precision, logic, and readability within any particular document.
Arabic Numerals Versus Spell-out
When to Use Arabic Numerals
When to Use Arabic Numerals |
Example |
Comment |
|---|---|---|
When a single-digit whole number is used as an adjective |
8-digit code |
|
For 10 and greater whole numbers |
ESP8266 has 17 GPIO pins. |
For large numbers that are not expressed with high precision, the text form may be a combination of numerals and words, e.g., 7 billion people. |
For 2-digit ordinals and larger |
2nd, 10th |
|
Measurements |
|
This is true whether the measurement is spelled out, abbreviated, or replaced by a symbol. |
To express dates, the time of day, pages, chapters, figures, steps, notes, and numbered items in documents |
|
This rule does not apply to expressions with hours, days, weeks, or other units of time. Example: 24 hours, two days, three years |
Percentages |
90% duty cycle |
|
When used as input |
Type 1, and then press Enter. |
|
When representing parameter values |
The default value of this register is 0. |
When to Spell Out Numbers
When to Spell out Numerals |
Example |
Comment |
|---|---|---|
Single-digit whole numbers |
ESP32 has three UART controllers. |
|
While beginning a sentence with a number |
Eighteen pads have low power capabilities and analog functions. |
It is better to reword the sentence so that the number comes later. Example: Out of the 40 physical GPIO pads, 18 pads have low power capabilities and analog functions. |
Fractions |
one-third |
|
Single-digit ordinal numbers |
first, second |
Maintain consistency among categories of information; that is, if one number in a category requires a numeral, use numerals for all numbers in that category.
Example
Preferred |
Avoid |
|---|---|
ESP32-S2 has 1 LCD interface, 2 UART interfaces, and 43 GPIO interfaces. |
ESP32-S2 has one LCD interface, two UART interfaces, and 43 GPIO interfaces. |
When two numbers that refer to separate categories must appear together, spell out one of them.
Example
Preferred |
Avoid |
|---|---|
two 8-bit D/A converters |
2 8-bit D/A converters |
10,000 and Greater Numbers
Use a comma “,” to mark off groups of three digits for numbers of five digits or more.
Example
10,240 bytes
10,000 B.C.
Exception
Do not use commas in page numbers, addresses, and decimal fractions.
Example
page 10011
Pune-411045
3.14159
When Referring to Quantities in a List
In the English version, omit the prefix ‘1 x’ when an item is in a single quantity, opting to simply name the item. For multiple quantities:
Spell out numbers for single-digit whole numbers.
Use Arabic numerals for 10 and greater whole numbers.
Example
Prefferred |
Avoid |
|
|
In the Chinese version, omit the prefix ‘1 x’ when an item is in a single quantity, opting to simply name the item. For multiple quantities, use Arabic numerals for all numbers.
Example
Prefferred |
Avoid |
|
|
Numeric Ranges, Dimensions, Series, and Placement of Units
A range of numbers and the accompanying unit can be expressed with a single unit symbol after the second number of the range, except when the symbol cannot be separated from the number (e.g., “%” symbol). Alternatively, the unit symbol may follow both numbers of the range. Whichever style is selected, use it consistently.
Example
Correct |
Incorrect |
|---|---|
23 to 47 kV |
|
23 kV to 47 kV |
|
10% to 15% |
10 to 15% |
If a range begins a sentence, spell out the first number and write the second as a numeral, or recast the sentence. Generally, any accompanying units will appear only after the second number and may be abbreviated. If the unit must also appear after the first number (as for “%” symbol), then write out both units or recast the sentence.
Example
Correct |
Incorrect |
Comment |
|---|---|---|
Eighty to 240 MHz of frequency is available for the CPU clock. |
80 to 240 MHz of frequency is available for the CPU clock. |
It would be better to recast the sentence into “CPU clock frequency is adjustable from 80 MHz to 240 MHz”. |
For dimensions, use a multiplication symbol (not a small letter “x”) or the word “by” to separate the measurements.
Example
10 × 55 × 5 mm or 10 mm × 55 mm × 5 mm
For a series of numbers, place the unit after the last numeral only, except when the unit symbol cannot be separated from the number.
Example
Correct |
Incorrect |
|---|---|
12, 17, 43, and 66 kV |
|
diameters of 5 and 9 mm |
|
15%, 22%, or 31% |
15, 22, or 31% |
For more information on using units of measure and unit symbols, please refer to Chapter Measurement Units and Abbreviations.
When Referring to Money
Currency Sign vs. Currency Code
It is recommended that currency amounts are expressed in accordance with the International Organization for Standardization (ISO) currency codes, instead of currency signs. Currency codes are specific to a currency, and cannot be confused or misinterpreted by the reader. Currency symbols such as the dollar sign ($) are not unique and are easily misread.
Example
Preferred |
Avoid |
|---|---|
The ESP32-DevKitC is priced at 55 CNY. |
The ESP32-DevKitC is priced at ¥55. |
The following table shows examples of currency codes.
Currency |
Code |
|---|---|
yuan renminbi |
CNY |
U.S. dollar |
USD |
Canadian dollar |
CAD |
Hong Kong dollar |
HKD |
euro |
EUR |
pound sterling |
GBP |
Swiss franc |
CHF |
yen |
JPY |
If you do need to use a currency sign, place it before the figure: ¥300, £100, etc. Always make clear to what currency you are referring.
Abbreviations
Avoid using abbreviations (e.g., m, M, MM for millions, K for thousands), when referring to money in technical context. In financial or other contexts, please consult department-specific guidelines.
Fractions and Decimals
Hyphenate spelled-out fractions used as adjectives or nouns.
Example
One-third of the book
Two-thirds completed
Write decimals with a period (full stop), not a comma: 0.75, 6.4.
When units of measure are not abbreviated, use the singular for quantities of one or less, except for zero, which takes the plural.
Example
0.5 inch
0 inches
5 inches
Phone Numbers
It is recommended that telephone numbers follow the International Telecommunication Union (ITU) standard: ITU-TE.123.
International telephone numbers begin with the plus sign followed immediately by the country code, then by the area code, and the number.
Example
You can reach Espressif by calling +86 021 6### ####.
The leading plus (+) signifies the international prefix. Spaces are used to visually separate groups of numbers.
National telephone numbers begin with area code included in parentheses followed by the number.
Example
You can reach Espressif by calling (021) 6### ####.
The parentheses indicate that the area code is not always dialed and they should not be used in an international number.
For better readability, please use non-breaking spaces to keep telephone numbers on the same line. If a telephone number is close to the end of the line, you get +86 021 6### ####. The number is treated as one word.
Addresses (Mailing)
Mailing addresses may have different standard formats in different places. Please follow the mailing address formats when writing Espressif corporate addresses.
Espressif China Office Mailing Address Format in Chinese
Address Elements |
Description |
|---|---|
上海浦东新区张江高科 |
[province, city, district] |
碧波路 690 号 2 号楼 101 室 |
[street name with street number, building name or number, room number] |
乐鑫信息科技（上海）股份有限公司 |
[company name] |
邮编 201203 |
[postal code] |
Espressif China Mailing Address Format in English
Address Elements |
Description |
|---|---|
Espressif Systems (Shanghai) Co., Ltd. |
[company name] |
Suite 101, Block 2, 690 Bibo Road |
[room number, building name or number, street name] |
Zhangjiang High-Tech Park, Pudong |
[district, city] |
Shanghai, China 201203 |
[province, country, postal code] |
Espressif Czech Republic Office Mailing Address Format
Address Elements |
Description |
|---|---|
Espressif Systems (Czech) s.r.o. |
[company name] |
Holandská 878/2 |
[street name + block number and/or building number] |
639 00 Brno-Štýrˇice |
[postal code + city name] |
Czech Republic |
[country] |
Espressif India Office Mailing Address Format
Address Elements |
Description |
|---|---|
Espressif Systems (India) Private Limited |
[company name] |
G-1, Eco Tower |
[flat number, building name] |
Baner-Pashan Link Road |
[street number, street name] |
Baner |
[locality or neighborhood] |
Pune-411045 |
[city, postal code] |
Maharashtra, India |
[country] |
Numbers in Chinese Text
If Arabic numerals are used in English text, please use Arabic numerals in the translated text. If English words are used in English text, please use Chinese words in the translated text.
Example
English |
Translated Text |
Notes |
|---|---|---|
20 mm |
20 mm |
|
7 billion people |
70 亿人口 |
|
10% |
10% |
|
10 percent |
百分之十 |
For percentages, don’t mix numbers and words, e.g., 百分之 10. |
one-third |
三分之一 |
When Referring to Numbers in Examples or Interfaces
Represent numbers taken from examples or the user interface exactly as they appear in the example or the user interface.
Example (see Figure below)
Preferred |
Avoid |
|---|---|
See 123-45-678, as shown in the interface below. |
See 123 45 678, as shown in the interface below. |
Example for Representation of Numbers
When to Use Plus Signs
The plus sign “+” is usually used to indicate that two or more numbers should be added together, or to indicate a positive number such as +85 °C。
In some cases, it is also used to indicate “over” or “more than” when placed after a number. However, it is strongly recommended to avoid such expression and use “>”, “more than” or other to express the meaning in formal technical writing and official documentation.
Example :
Preferred |
Avoid |
|---|---|
The soldering time should be more than 30 s. |
The soldering time should be 30+ s. |
Use plus signs to indicate “more than” only:
In informal texts
When there is only limited space and conciseness appears to be most important
Numeral Systems
A numeral system is a writing system for expressing numbers. In general, we recommend decimal and hexadecimal numbers.
When describing large numbers relevant to software development or system design, for example, in programming guides or register descriptions, please use hexadecimal numbers. They provide a human-friendly representation of binary-coded values, and are less prone to errors as they represent large numbers with fewer digits. Please add “0x” to the beginning of hexadecimal values.
Example
If the pin level of ADDR is low, then the address is 0x23, otherwise it is 0x5C. Configure the field EFUSE_OP_CODE of register EFUSE_CONF_REG to 0x5A5A.
When describing quantities, measurements, money, time, etc., please use decimal numbers.
Do not use Verilog number format in the above cases, e.g., 1’b1 or 1’h0 in register descriptions. This is not easy to read and may lead to mixed use of different numeral systems.
Example
Preferred
Avoid
1
1’b1
0
1’h0