1 @c Copyright (C) 2018-2023 Free Software Foundation, Inc.
2 @c Free Software Foundation, Inc.
3 @c This is part of the GCC manual.
4 @c For copying conditions, see the file gcc.texi.
6 @node User Experience Guidelines
7 @chapter User Experience Guidelines
8 @cindex user experience guidelines
9 @cindex guidelines, user experience
11 To borrow a slogan from
12 @uref{https://elm-lang.org/news/compilers-as-assistants, Elm},
15 @strong{Compilers should be assistants, not adversaries.} A compiler should
16 not just detect bugs, it should then help you understand why there is a bug.
17 It should not berate you in a robot voice, it should give you specific hints
18 that help you write better code. Ultimately, a compiler should make
19 programming faster and more fun!
20 @author Evan Czaplicki
23 This chapter provides guidelines on how to implement diagnostics and
24 command-line options in ways that we hope achieve the above ideal.
27 * Guidelines for Diagnostics:: How to implement diagnostics.
28 * Guidelines for Options:: Guidelines for command-line options.
32 @node Guidelines for Diagnostics
33 @section Guidelines for Diagnostics
34 @cindex guidelines for diagnostics
35 @cindex diagnostics, guidelines for
37 @subsection Talk in terms of the user's code
39 Diagnostics should be worded in terms of the user's source code, and the
40 source language, rather than GCC's own implementation details.
42 @subsection Diagnostics are actionable
43 @cindex diagnostics, actionable
45 A good diagnostic is @dfn{actionable}: it should assist the user in
48 Consider what an end user will want to do when encountering a diagnostic.
50 Given an error, an end user will think: ``How do I fix this?''
52 Given a warning, an end user will think:
56 ``Is this a real problem?''
60 if they decide it's genuine: ``How do I fix this?''
63 A good diagnostic provides pertinent information to allow the user to
64 easily answer the above questions.
66 @subsection The user's attention is important
68 A perfect compiler would issue a warning on every aspect of the user's
69 source code that ought to be fixed, and issue no other warnings.
70 Naturally, this ideal is impossible to achieve.
72 @cindex signal-to-noise ratio (metaphorical usage for diagnostics)
73 @cindex diagnostics, false positive
74 @cindex diagnostics, true positive
75 @cindex false positive
78 Warnings should have a good @dfn{signal-to-noise ratio}: we should have few
79 @dfn{false positives} (falsely issuing a warning when no warning is
80 warranted) and few @dfn{false negatives} (failing to issue a warning when
81 one @emph{is} justified).
83 Note that a false positive can mean, in practice, a warning that the
84 user doesn't agree with. Ideally a diagnostic should contain enough
85 information to allow the user to make an informed choice about whether
86 they should care (and how to fix it), but a balance must be drawn against
87 overloading the user with irrelevant data.
89 @subsection Sometimes the user didn't write the code
91 GCC is typically used in two different ways:
95 Semi-interactive usage: GCC is used as a development tool when the user
96 is writing code, as the ``compile'' part of the ``edit-compile-debug''
97 cycle. The user is actively hacking on the code themself (perhaps a
98 project they wrote, or someone else's), where they just made a change
99 to the code and want to see what happens, and to be warned about
103 Batch rebuilds: where the user is recompiling one or more existing
104 packages, and GCC is a detail that's being invoked by various build
105 scripts. Examples include a user trying to bring up an operating system
106 consisting of hundreds of packages on a new CPU architecture, where the
107 packages were written by many different people, or simply rebuilding
108 packages after a dependency changed, where the user is hoping
109 ``nothing breaks'', since they are unfamiliar with the code.
112 Keep both of these styles of usage in mind when implementing diagnostics.
114 @subsection Precision of Wording
116 Provide the user with details that allow them to identify what the
117 problem is. For example, the vaguely-worded message:
120 demo.c:1:1: warning: 'noinline' attribute ignored [-Wattributes]
121 1 | int foo __attribute__((noinline));
126 doesn't tell the user why the attribute was ignored, or what kind of
127 entity the compiler thought the attribute was being applied to (the
128 source location for the diagnostic is also poor;
129 @pxref{input_location_example,,discussion of @code{input_location}}).
130 A better message would be:
133 demo.c:1:24: warning: attribute 'noinline' on variable 'foo' was
134 ignored [-Wattributes]
135 1 | int foo __attribute__((noinline));
136 | ~~~ ~~~~~~~~~~~~~~~^~~~~~~~~
137 demo.c:1:24: note: attribute 'noinline' is only applicable to functions
141 which spells out the missing information (and fixes the location
142 information, as discussed below).
144 The above example uses a note to avoid a combinatorial explosion of possible
147 @subsection Try the diagnostic on real-world code
149 It's worth testing a new warning on many instances of real-world code,
150 written by different people, and seeing what it complains about, and
151 what it doesn't complain about.
153 This may suggest heuristics that silence common false positives.
155 It may also suggest ways to improve the precision of the message.
157 @subsection Make mismatches clear
159 Many diagnostics relate to a mismatch between two different places in the
160 user's source code. Examples include:
163 a type mismatch, where the type at a usage site does not match the type
167 the argument count at a call site does not match the parameter count
171 something is erroneously duplicated (e.g.@: an error, due to breaking a
172 uniqueness requirement, or a warning, if it's suggestive of a bug)
175 an ``opened'' syntactic construct (such as an open-parenthesis) is not
178 @c TODO: more examples?
181 In each case, the diagnostic should indicate @strong{both} pertinent
182 locations (so that the user can easily see the problem and how to fix it).
184 The standard way to do this is with a note (via @code{inform}). For
188 auto_diagnostic_group d;
189 if (warning_at (loc, OPT_Wduplicated_cond,
190 "duplicated %<if%> condition"))
191 inform (EXPR_LOCATION (t), "previously used here");
198 demo.c: In function 'test':
199 demo.c:5:17: warning: duplicated 'if' condition [-Wduplicated-cond]
200 5 | else if (flag > 3)
202 demo.c:3:12: note: previously used here
208 The @code{inform} call should be guarded by the return value from the
209 @code{warning_at} call so that the note isn't emitted when the warning
212 For cases involving punctuation where the locations might be near
213 each other, they can be conditionally consolidated via
214 @code{gcc_rich_location::add_location_if_nearby}:
217 auto_diagnostic_group d;
218 gcc_rich_location richloc (primary_loc);
219 bool added secondary = richloc.add_location_if_nearby (secondary_loc);
220 error_at (&richloc, "main message");
221 if (!added secondary)
222 inform (secondary_loc, "message for secondary");
226 This will emit either one diagnostic with two locations:
228 demo.c:42:10: error: main message
237 demo.c:42:4: error: main message
240 demo.c:40:2: note: message for secondary
245 @subsection Location Information
246 @cindex diagnostics, locations
247 @cindex location information
248 @cindex source code, location information
251 GCC's @code{location_t} type can support both ordinary locations,
252 and locations relating to a macro expansion.
254 As of GCC 6, ordinary locations changed from supporting just a
255 point in the user's source code to supporting three points: the
256 @dfn{caret} location, plus a start and a finish:
267 Tokens coming out of libcpp have locations of the form @code{caret == start},
268 such as for @code{foo} here:
278 Compound expressions should be reported using the location of the
279 expression as a whole, rather than just of one token within it.
281 For example, in @code{-Wformat}, rather than underlining just the first
282 token of a bad argument:
285 printf("hello %i %s", (long)0, "world");
291 the whole of the expression should be underlined, so that the user can
292 easily identify what is being referred to:
295 printf("hello %i %s", (long)0, "world");
302 Avoid using the @code{input_location} global, and the diagnostic functions
303 that implicitly use it---use @code{error_at} and @code{warning_at} rather
304 than @code{error} and @code{warning}, and provide the most appropriate
305 @code{location_t} value available at that phase of the compilation. It's
306 possible to supply secondary @code{location_t} values via
307 @code{rich_location}.
310 @anchor{input_location_example}
311 For example, in the example of imprecise wording above, generating the
312 diagnostic using @code{warning}:
315 // BAD: implicitly uses @code{input_location}
316 warning (OPT_Wattributes, "%qE attribute ignored", name);
323 // BAD: uses @code{input_location}
324 demo.c:1:1: warning: 'noinline' attribute ignored [-Wattributes]
325 1 | int foo __attribute__((noinline));
330 which thus happened to use the location of the @code{int} token, rather
331 than that of the attribute. Using @code{warning_at} with the location of
332 the attribute, providing the location of the declaration in question
333 as a secondary location, and adding a note:
336 auto_diagnostic_group d;
337 gcc_rich_location richloc (attrib_loc);
338 richloc.add_range (decl_loc);
339 if (warning_at (OPT_Wattributes, &richloc,
340 "attribute %qE on variable %qE was ignored", name))
341 inform (attrib_loc, "attribute %qE is only applicable to functions");
348 // OK: use location of attribute, with a secondary location
349 demo.c:1:24: warning: attribute 'noinline' on variable 'foo' was
350 ignored [-Wattributes]
351 1 | int foo __attribute__((noinline));
352 | ~~~ ~~~~~~~~~~~~~~~^~~~~~~~~
353 demo.c:1:24: note: attribute 'noinline' is only applicable to functions
356 @c TODO labelling of ranges
358 @subsection Coding Conventions
360 See the @uref{https://gcc.gnu.org/codingconventions.html#Diagnostics,
361 diagnostics section} of the GCC coding conventions.
363 In the C++ front end, when comparing two types in a message, use @samp{%H}
364 and @samp{%I} rather than @samp{%T}, as this allows the diagnostics
365 subsystem to highlight differences between template-based types.
366 For example, rather than using @samp{%qT}:
369 // BAD: a pair of %qT used in C++ front end for type comparison
370 error_at (loc, "could not convert %qE from %qT to %qT", expr,
371 TREE_TYPE (expr), type);
378 error: could not convert 'map<int, double>()' from 'map<int,double>'
383 using @samp{%H} and @samp{%I} (via @samp{%qH} and @samp{%qI}):
386 // OK: compare types in C++ front end via %qH and %qI
387 error_at (loc, "could not convert %qE from %qH to %qI", expr,
388 TREE_TYPE (expr), type);
392 allows the above output to be simplified to:
395 error: could not convert 'map<int, double>()' from 'map<[...],double>'
400 where the @code{double} and @code{int} are colorized to highlight them.
402 @c %H and %I were added in r248698.
404 @subsection Group logically-related diagnostics
406 Use @code{auto_diagnostic_group} when issuing multiple related
407 diagnostics (seen in various examples on this page). This informs the
408 diagnostic subsystem that all diagnostics issued within the lifetime
409 of the @code{auto_diagnostic_group} are related. For example,
410 @option{-fdiagnostics-format=json} will treat the first diagnostic
411 emitted within the group as a top-level diagnostic, and all subsequent
412 diagnostics within the group as its children.
415 Text should be quoted by either using the @samp{q} modifier in a directive
416 such as @samp{%qE}, or by enclosing the quoted text in a pair of @samp{%<}
417 and @samp{%>} directives, and never by using explicit quote characters.
418 The directives handle the appropriate quote characters for each language
419 and apply the correct color or highlighting.
421 The following elements should be quoted in GCC diagnostics:
429 Boolean, numerical, character, and string constants that appear in the
432 Identifiers, including function, macro, type, and variable names.
435 Other elements such as numbers that do not refer to numeric constants that
436 appear in the source code should not be quoted. For example, in the message:
439 argument %d of %qE must be a pointer type
443 since the argument number does not refer to a numerical constant in the
444 source code it should not be quoted.
446 @subsection Spelling and Terminology
448 See the @uref{https://gcc.gnu.org/codingconventions.html#Spelling
449 Spelling, terminology and markup} section of the GCC coding conventions.
451 @subsection Fix-it hints
453 @cindex diagnostics guidelines, fix-it hints
455 GCC's diagnostic subsystem can emit @dfn{fix-it hints}: small suggested
456 edits to the user's source code.
458 They are printed by default underneath the code in question. They
459 can also be viewed via @option{-fdiagnostics-generate-patch} and
460 @option{-fdiagnostics-parseable-fixits}. With the latter, an IDE
461 ought to be able to offer to automatically apply the suggested fix.
463 Fix-it hints contain code fragments, and thus they should not be marked
466 Fix-it hints can be added to a diagnostic by using a @code{rich_location}
467 rather than a @code{location_t} - the fix-it hints are added to the
468 @code{rich_location} using one of the various @code{add_fixit} member
469 functions of @code{rich_location}. They are documented with
470 @code{rich_location} in @file{libcpp/line-map.h}.
471 It's easiest to use the @code{gcc_rich_location} subclass of
472 @code{rich_location} found in @file{gcc-rich-location.h}, as this
473 implicitly supplies the @code{line_table} variable.
478 if (const char *suggestion = hint.suggestion ())
480 gcc_rich_location richloc (location);
481 richloc.add_fixit_replace (suggestion);
483 "%qE does not name a type; did you mean %qs?",
492 spellcheck-typenames.C:73:1: error: 'singed' does not name a type; did
499 Non-trivial edits can be built up by adding multiple fix-it hints to one
500 @code{rich_location}. It's best to express the edits in terms of the
501 locations of individual tokens. Various handy functions for adding
502 fix-it hints for idiomatic C and C++ can be seen in
503 @file{gcc-rich-location.h}.
505 @subsubsection Fix-it hints should work
507 When implementing a fix-it hint, please verify that the suggested edit
508 leads to fixed, compilable code. (Unfortunately, this currently must be
509 done by hand using @option{-fdiagnostics-generate-patch}. It would be
510 good to have an automated way of verifying that fix-it hints actually fix
513 For example, a ``gotcha'' here is to forget to add a space when adding a
514 missing reserved word. Consider a C++ fix-it hint that adds
515 @code{typename} in front of a template declaration. A naive way to
516 implement this might be:
519 gcc_rich_location richloc (loc);
520 // BAD: insertion is missing a trailing space
521 richloc.add_fixit_insert_before ("typename");
522 error_at (&richloc, "need %<typename%> before %<%T::%E%> because "
523 "%qT is a dependent scope",
524 parser->scope, id, parser->scope);
528 When applied to the code, this might lead to:
535 being ``corrected'' to:
542 In this case, the correct thing to do is to add a trailing space after
546 gcc_rich_location richloc (loc);
547 // OK: note that here we have a trailing space
548 richloc.add_fixit_insert_before ("typename ");
549 error_at (&richloc, "need %<typename%> before %<%T::%E%> because "
550 "%qT is a dependent scope",
551 parser->scope, id, parser->scope);
555 leading to this corrected code:
561 @subsubsection Express deletion in terms of deletion, not replacement
563 It's best to express deletion suggestions in terms of deletion fix-it
564 hints, rather than replacement fix-it hints. For example, consider this:
567 auto_diagnostic_group d;
568 gcc_rich_location richloc (location_of (retval));
569 tree name = DECL_NAME (arg);
570 richloc.add_fixit_replace (IDENTIFIER_POINTER (name));
571 warning_at (&richloc, OPT_Wredundant_move,
572 "redundant move in return statement");
576 which is intended to e.g.@: replace a @code{std::move} with the underlying
580 return std::move (retval);
586 where the change has been expressed as replacement, replacing
587 with the name of the declaration.
588 This works for simple cases, but consider this case:
591 #ifdef SOME_CONFIG_FLAG
592 # define CONFIGURY_GLOBAL global_a
594 # define CONFIGURY_GLOBAL global_b
599 return std::move (CONFIGURY_GLOBAL /* some comment */);
604 The above implementation erroneously strips out the macro and the
605 comment in the fix-it hint:
608 return std::move (CONFIGURY_GLOBAL /* some comment */);
609 ~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
614 and thus this resulting code:
621 It's better to do deletions in terms of deletions; deleting the
622 @code{std::move (} and the trailing close-paren, leading to
626 return std::move (CONFIGURY_GLOBAL /* some comment */);
627 ~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
628 CONFIGURY_GLOBAL /* some comment */
632 and thus this result:
635 return CONFIGURY_GLOBAL /* some comment */;
639 Unfortunately, the pertinent @code{location_t} values are not always
642 @c the above was https://gcc.gnu.org/ml/gcc-patches/2018-08/msg01474.html
644 @subsubsection Multiple suggestions
646 In the rare cases where you need to suggest more than one mutually
647 exclusive solution to a problem, this can be done by emitting
648 multiple notes and calling
649 @code{rich_location::fixits_cannot_be_auto_applied} on each note's
650 @code{rich_location}. If this is called, then the fix-it hints in
651 the @code{rich_location} will be printed, but will not be added to
655 @node Guidelines for Options
656 @section Guidelines for Options
657 @cindex command-line options, guidelines for
658 @cindex options, guidelines for
659 @cindex guidelines for options