Formatting developer text elements
Consistent text formatting helps readers locate and interpret information. Follow these formatting conventions for text elements commonly used in content for developers.
For information about referring to UI elements, see Formatting text in instructions.
See also
Capitalization
Formatting common text elements
Procedures and instructions
| Element | Convention | Example |
|---|---|---|
| Attributes | Bold. Capitalization varies. | IfOutputPrecision |
| Classes (predefined) | Bold. Capitalization varies. | ios filebuf BitArray |
| Classes (user-defined) | Bold. Capitalization varies. | BlueTimerControl |
| Code samples, including keywords and variables within text and as separate paragraphs, and user-defined program elements within text | Monospace. | #include <iostream.h> void main () |
| Command-line commands | Bold. All lowercase. | copy |
| Command-line options (also known as switches or flags) | Bold. Capitalize the way the option must be typed. | /a /Aw |
| Constants | Usually bold. Capitalization varies. | INT_MAX bDenyWrite CS_DBLCLKS |
| Control classes | Often bold. All uppercase. | EDIT control class |
| Data formats | Often bold. All uppercase. | CF_DIB format |
| Data structures and their members (predefined) | Bold. Capitalization varies. | BITMAP bmBits CREATESTRUCT hInstance |
| Data types | Bold. Capitalization follows that of the API. | DWORD float HANDLE |
| Database names | Bold. The capitalization of database names varies. | Contoso database |
| Directives | Bold. | #include #define |
| Environment variables | Often all uppercase. | INCLUDE SESSIONNAME |
| Error messages | Sentence-style capitalization. Enclose in quotation marks when referencing error messages in text. | An error occurred during report processing. If you see the error message, "Placeholder text in a content control contains items that aren't valid," remove floating objects, revision marks, or content controls from placeholder text, and try again. |
| Event names | Bold. Treatment of event names varies. | In the OnClick event procedure .... |
| Fields (members of a class or structure) | Bold. Treatment of field names varies. | IfHeight biPlanes |
| File attributes | All lowercase. | The attrib command displays, sets, or removes the read-only, archive, system, and hidden attributes assigned to files or directories. |
| File name extensions | All lowercase. | .mdb .doc |
| File names (user-defined examples) | Title-style capitalization. It's OK to use internal capital letters in file names for readability. | My Taxes for 2016 MyTaxesFor2016 |
| Folder and directory names (user-defined examples) | Sentence-style capitalization. It's OK to use internal capital letters in folder and directory names for readability. | Vacation and sick pay MyFiles\Accounting\Payroll\VacPay |
| Functions (predefined) | Usually bold. Capitalization varies. | CompactDatabase CWnd::CreateEx FadePic |
| Handles | All uppercase. | HWND |
| Keywords (language and operating system) | Bold. Capitalization follows the application programming interface. | main True void |
| Logical operators | Bold. All uppercase. | AND XOR |
| Macros | Usually all uppercase. Bold if predefined. Might be monospace if user defined. | LOWORDMASKROP |
| Markup language elements (tags) | Bold. Capitalization varies. | <img> <input type=text> <!DOCTYPE html> |
| Mathematical constants and variables | Italic. | a2 + b2 = c2 |
| Members | Bold. Capitalization varies. | ulNumCharsAllowed |
| Methods | Bold. Capitalization varies. | OpenForm GetPrevious |
| New terms | Italicize the first mention of a new term if you're going to define it immediately in text. | Microsoft Exchange consists of both server and client components. |
| Operators | Bold. | +, - sizeof |
| Parameters | Italic. Capitalization varies. | Hdc grfFlagClientBinding |
| Placeholders (in syntax and in user input) | Italic. | /v: version Enter password. |
| Ports | All uppercase. | LPT1 |
| Products, services, apps, and trademarks | Usually title-style capitalization. Check the Microsoft trademark list for capitalization of trademarked names. | Microsoft Arc Touch Mouse Microsoft Word Surface Pro Notepad Network Connections Makefile RC program |
| Properties | Usually bold. Capitalization varies. | M_bClipped AbsolutePosition Message ID |
| Registers | All uppercase. Treatment varies. | DS |
| Registry settings | Subtrees (first-level items) all uppercase. Separated by underscores. Usually bold. Registry keys (second-level items) follow the capitalization of the UI. Registry subkeys (below the second level) follow the capitalization of the Regedit UI. |
HKEY_CLASSES_ROOT HKEY_LOCAL_MACHINE SOFTWARE ApplicationIdentifier Microsoft |
| Statements | Bold. Capitalization varies. | IMPORTS LIBRARY |
| Structures | Usually bold. Capitalization varies. | ACCESSTIMEOUT |
| Switches | Bold. Usually lowercase. | build: commands |
| UI text or strings | Sentence-style capitalization. | Import from file Create a new resource See all your resources Manually trigger a flow Report a bug |
| URLs | All lowercase for complete URLs. If necessary, line-break long URLs before a slash. Don't hyphenate. See also URLs and web addresses. |
www.microsoft.com msdn.microsoft.com/downloads |
| User input | Usually lowercase, unless case sensitive. Bold or italic, depending on the element. If the user input string contains placeholder text, use italic for that text. | Enter hello world Enter -p password |
| Values | All uppercase. | DIB_PAL_COLORS |
| Variables | Treatment varies. | bEmpty m_nParams file_name |
| XML schema elements | Bold. Capitalization varies. | ElementType element xml:space attribute |