Chapter 9: Style

Introduction

The chapter introduces readability as a requirement for C code and explains how human limits and project culture shape coding style.

• Code as human documentation: Explain why C code must be readable to people as well as usable by a compiler.
  Why it matters: Readable code helps people understand what a system is intended to do.
• Human limits on code visibility: Describe how limited vision and short-term memory constrain readable code.
  Why it matters: Code that fits within what a reader can readily see demands less memory.
• Project culture and style: Explain why coding style should account for a project’s established habits.
  Why it matters: Adapting to a project’s conventions avoids unproductive arguments over personal preferences.

Key terms: readable, intended behavior, short-term memory, field of vision, window, coding style, culture, cultural space

9.1 Formatting

This section explains why consistent C formatting helps people read code and why editors and project-wide tools should apply it automatically.

• Consistent formatting for readers: Explain why C code should follow a consistent formatting style even though the compiler tolerates poorly formatted code. Describe the kinds of choices a style covers, such as indentation, bracket placement, and spacing.
  Why it matters: A predictable layout lets you and your collaborators read unfamiliar code more quickly.
• Automatic editor formatting: Explain why the section recommends using an editor or other tool to format code rather than meticulously applying every style rule by hand.
  Why it matters: Automation makes a consistent style easier to maintain without spending attention on every space and bracket.
• Project-wide formatting policy: Explain why larger projects should enforce one formatting policy across code shared with others, and how the section suggests doing so.
  Why it matters: Shared formatting keeps layout changes from making successive versions of project code harder to compare.

Key terms: formatting, white space, coding style, text editor, automatically format, formatting rules, formatting policy, command-line tools, differences between versions

9.2 Naming

This section explains how to choose C identifiers that avoid technical conflicts and communicate their purpose clearly.

• Reserved Identifier Constraints: Explain why identifiers exposed in header files must conform to C’s naming restrictions and how reserved names can cause conflicts.
  Why it matters: A name that works on your machine may conflict with a header or implementation elsewhere.
• Limited Public Identifier Exposure: Explain how limiting exposed names and choosing distinctive prefixes reduce naming conflicts, including conflicts involving macros.
  Why it matters: A smaller, distinctively named public interface gives other code fewer opportunities to collide with yours.
• Recognizable Distinguishable Names: Explain why a good name must be quickly distinguishable in its context, and why short names can work in a narrow scope but obscure abbreviations can fail for functions.
  Why it matters: Choosing names for their context helps readers recognize what code means without repeatedly searching for declarations.
• Pragmatic Naming Conventions: Describe the common multiword naming conventions discussed and explain why none is an absolute rule for producing good names.
  Why it matters: A consistent convention helps, but it cannot replace judging whether each name is useful to a reader.
• Purposeful File Scope Names: Distinguish what type names, global constants, global variables, and functions or functional macros should communicate.
  Why it matters: Names used beyond a small local context should tell callers what kind of thing they refer to and what it does.

Key terms: reserved identifier, header file, file scope, global space of identifiers, application programming interface, naming prefixes, macro, recognizable, distinguishable, scope

9.3 Internationalization, so to speak

This section explains how project language choices and Unicode identifier rules can make C code appropriate and readable for different communities.

• Project language choice: Explain why a project's natural language for names and comments should accommodate its participants rather than default automatically to English, and distinguish that choice from the languages a program supports for users.
  Why it matters: A team can choose readable names and comments without treating English as the only legitimate language for code.
• Domain notation in documentation: Explain why documentation should be free to use the scripts and symbols conventional to its technical domain.
  Why it matters: Documentation is clearer when it uses notation its intended readers already recognize.
• C23 identifier normalization: Describe how C23's Unicode-based identifier rules use Normalization Form C to address character sequences that can represent the same letter, and state the resulting restriction on alphabetic letters.
  Why it matters: Normalization provides a rule for which Unicode letters can be used as C identifiers.
• Identifier character distinguishability: Explain why letters from different scripts and variants of decimal digits should be used in identifiers only when readers can distinguish them.
  Why it matters: Identifiers that look alike can be difficult to read correctly even when their characters satisfy the language rules.
• Subscript identifier portability: State why using subscript or superscript letters in identifiers is not portable, even if a local compiler accepts them.
  Why it matters: A name accepted by one compiler may fail elsewhere.

Key terms: natural language, project, variable and function names, code comments, technical language, domain-specific problems, mathematical notation, documentation, C23, UAX #31

9.4 Summary