1 @c Copyright (C) 2018 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/blog/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 Precision of Wording
91 Provide the user with details that allow them to identify what the
92 problem is. For example, the vaguely-worded message:
95 demo.c:1:1: warning: 'noinline' attribute ignored [-Wattributes]
96 1 | int foo __attribute__((noinline));
101 doesn't tell the user why the attribute was ignored, or what kind of
102 entity the compiler thought the attribute was being applied to (the
103 source location for the diagnostic is also poor;
104 @pxref{input_location_example,,discussion of @code{input_location}}).
105 A better message would be:
108 demo.c:1:24: warning: attribute 'noinline' on variable 'foo' was
109 ignored [-Wattributes]
110 1 | int foo __attribute__((noinline));
111 | ~~~ ~~~~~~~~~~~~~~~^~~~~~~~~
112 demo.c:1:24: note: attribute 'noinline' is only applicable to functions
116 which spells out the missing information (and fixes the location
117 information, as discussed below).
119 The above example uses a note to avoid a combinatorial explosion of possible
122 @subsection Try the diagnostic on real-world code
124 It's worth testing a new warning on many instances of real-world code,
125 written by different people, and seeing what it complains about, and
126 what it doesn't complain about.
128 This may suggest heuristics that silence common false positives.
130 It may also suggest ways to improve the precision of the message.
132 @subsection Make mismatches clear
134 Many diagnostics relate to a mismatch between two different places in the
135 user's source code. Examples include:
138 a type mismatch, where the type at a usage site does not match the type
142 the argument count at a call site does not match the parameter count
146 something is erroneously duplicated (e.g.@: an error, due to breaking a
147 uniqueness requirement, or a warning, if it's suggestive of a bug)
150 an ``opened'' syntactic construct (such as an open-parenthesis) is not
153 @c TODO: more examples?
156 In each case, the diagnostic should indicate @strong{both} pertinent
157 locations (so that the user can easily see the problem and how to fix it).
159 The standard way to do this is with a note (via @code{inform}). For
163 auto_diagnostic_group d;
164 if (warning_at (loc, OPT_Wduplicated_cond,
165 "duplicated %<if%> condition"))
166 inform (EXPR_LOCATION (t), "previously used here");
173 demo.c: In function 'test':
174 demo.c:5:17: warning: duplicated 'if' condition [-Wduplicated-cond]
175 5 | else if (flag > 3)
177 demo.c:3:12: note: previously used here
183 The @code{inform} call should be guarded by the return value from the
184 @code{warning_at} call so that the note isn't emitted when the warning
187 For cases involving punctuation where the locations might be near
188 each other, they can be conditionally consolidated via
189 @code{gcc_rich_location::add_location_if_nearby}:
192 auto_diagnostic_group d;
193 gcc_rich_location richloc (primary_loc);
194 bool added secondary = richloc.add_location_if_nearby (secondary_loc);
195 error_at (&richloc, "main message");
196 if (!added secondary)
197 inform (secondary_loc, "message for secondary");
201 This will emit either one diagnostic with two locations:
203 demo.c:42:10: error: main message
212 demo.c:42:4: error: main message
215 demo.c:40:2: note: message for secondary
220 @subsection Location Information
221 @cindex diagnostics, locations
222 @cindex location information
223 @cindex source code, location information
226 GCC's @code{location_t} type can support both ordinary locations,
227 and locations relating to a macro expansion.
229 As of GCC 6, ordinary locations changed from supporting just a
230 point in the user's source code to supporting three points: the
231 @dfn{caret} location, plus a start and a finish:
242 Tokens coming out of libcpp have locations of the form @code{caret == start},
243 such as for @code{foo} here:
253 Compound expressions should be reported using the location of the
254 expression as a whole, rather than just of one token within it.
256 For example, in @code{-Wformat}, rather than underlining just the first
257 token of a bad argument:
260 printf("hello %i %s", (long)0, "world");
266 the whole of the expression should be underlined, so that the user can
267 easily identify what is being referred to:
270 printf("hello %i %s", (long)0, "world");
277 Avoid using the @code{input_location} global, and the diagnostic functions
278 that implicitly use it---use @code{error_at} and @code{warning_at} rather
279 than @code{error} and @code{warning}, and provide the most appropriate
280 @code{location_t} value available at that phase of the compilation. It's
281 possible to supply secondary @code{location_t} values via
282 @code{rich_location}.
285 @anchor{input_location_example}
286 For example, in the example of imprecise wording above, generating the
287 diagnostic using @code{warning}:
290 // BAD: implicitly uses @code{input_location}
291 warning (OPT_Wattributes, "%qE attribute ignored", name);
298 // BAD: uses @code{input_location}
299 demo.c:1:1: warning: 'noinline' attribute ignored [-Wattributes]
300 1 | int foo __attribute__((noinline));
305 which thus happened to use the location of the @code{int} token, rather
306 than that of the attribute. Using @code{warning_at} with the location of
307 the attribute, providing the location of the declaration in question
308 as a secondary location, and adding a note:
311 auto_diagnostic_group d;
312 gcc_rich_location richloc (attrib_loc);
313 richloc.add_range (decl_loc);
314 if (warning_at (OPT_Wattributes, &richloc,
315 "attribute %qE on variable %qE was ignored", name))
316 inform (attrib_loc, "attribute %qE is only applicable to functions");
323 // OK: use location of attribute, with a secondary location
324 demo.c:1:24: warning: attribute 'noinline' on variable 'foo' was
325 ignored [-Wattributes]
326 1 | int foo __attribute__((noinline));
327 | ~~~ ~~~~~~~~~~~~~~~^~~~~~~~~
328 demo.c:1:24: note: attribute 'noinline' is only applicable to functions
331 @c TODO labelling of ranges
333 @subsection Coding Conventions
335 See the @uref{https://gcc.gnu.org/codingconventions.html#Diagnostics,
336 diagnostics section} of the GCC coding conventions.
338 In the C++ front end, when comparing two types in a message, use @samp{%H}
339 and @samp{%I} rather than @samp{%T}, as this allows the diagnostics
340 subsystem to highlight differences between template-based types.
341 For example, rather than using @samp{%qT}:
344 // BAD: a pair of %qT used in C++ front end for type comparison
345 error_at (loc, "could not convert %qE from %qT to %qT", expr,
346 TREE_TYPE (expr), type);
353 error: could not convert 'map<int, double>()' from 'map<int,double>'
358 using @samp{%H} and @samp{%I} (via @samp{%qH} and @samp{%qI}):
361 // OK: compare types in C++ front end via %qH and %qI
362 error_at (loc, "could not convert %qE from %qH to %qI", expr,
363 TREE_TYPE (expr), type);
367 allows the above output to be simplified to:
370 error: could not convert 'map<int, double>()' from 'map<[...],double>'
375 where the @code{double} and @code{int} are colorized to highlight them.
377 @c %H and %I were added in r248698.
379 Use @code{auto_diagnostic_group} when issuing multiple related
380 diagnostics (seen in various examples on this page). This informs the
381 diagnostic subsystem that all diagnostics issued within the lifetime
382 of the @code{auto_diagnostic_group} are related. (Currently it doesn't
383 do anything with this information, but we may implement that in the
387 Text should be quoted by either using the @samp{q} modifier in a directive
388 such as @samp{%qE}, or by enclosing the quoted text in a pair of @samp{%<}
389 and @samp{%>} directives, and never by using explicit quote characters.
390 The directives handle the appropriate quote characters for each language
391 and apply the correct color or highlighting.
393 The following elements should be quoted in GCC diagnostics:
401 Boolean, numerical, character, and string constants that appear in the
404 Identifiers, including function, macro, type, and variable names.
407 Other elements such as numbers that do not refer to numeric constants that
408 appear in the source code should not be quoted. For example, in the message:
411 argument %d of %qE must be a pointer type
415 since the argument number does not refer to a numerical constant in the
416 source code it should not be quoted.
418 @subsection Spelling and Terminology
420 See the @uref{https://gcc.gnu.org/codingconventions.html#Spelling
421 Spelling, terminology and markup} section of the GCC coding conventions.
423 @subsection Fix-it hints
425 @cindex diagnostics guidelines, fix-it hints
427 GCC's diagnostic subsystem can emit @dfn{fix-it hints}: small suggested
428 edits to the user's source code.
430 They are printed by default underneath the code in question. They
431 can also be viewed via @option{-fdiagnostics-generate-patch} and
432 @option{-fdiagnostics-parseable-fixits}. With the latter, an IDE
433 ought to be able to offer to automatically apply the suggested fix.
435 Fix-it hints contain code fragments, and thus they should not be marked
438 Fix-it hints can be added to a diagnostic by using a @code{rich_location}
439 rather than a @code{location_t} - the fix-it hints are added to the
440 @code{rich_location} using one of the various @code{add_fixit} member
441 functions of @code{rich_location}. They are documented with
442 @code{rich_location} in @file{libcpp/line-map.h}.
443 It's easiest to use the @code{gcc_rich_location} subclass of
444 @code{rich_location} found in @file{gcc-rich-location.h}, as this
445 implicitly supplies the @code{line_table} variable.
450 if (const char *suggestion = hint.suggestion ())
452 gcc_rich_location richloc (location);
453 richloc.add_fixit_replace (suggestion);
455 "%qE does not name a type; did you mean %qs?",
464 spellcheck-typenames.C:73:1: error: 'singed' does not name a type; did
471 Non-trivial edits can be built up by adding multiple fix-it hints to one
472 @code{rich_location}. It's best to express the edits in terms of the
473 locations of individual tokens. Various handy functions for adding
474 fix-it hints for idiomatic C and C++ can be seen in
475 @file{gcc-rich-location.h}.
477 @subsubsection Fix-it hints should work
479 When implementing a fix-it hint, please verify that the suggested edit
480 leads to fixed, compilable code. (Unfortunately, this currently must be
481 done by hand using @option{-fdiagnostics-generate-patch}. It would be
482 good to have an automated way of verifying that fix-it hints actually fix
485 For example, a ``gotcha'' here is to forget to add a space when adding a
486 missing reserved word. Consider a C++ fix-it hint that adds
487 @code{typename} in front of a template declaration. A naive way to
488 implement this might be:
491 gcc_rich_location richloc (loc);
492 // BAD: insertion is missing a trailing space
493 richloc.add_fixit_insert_before ("typename");
494 error_at (&richloc, "need %<typename%> before %<%T::%E%> because "
495 "%qT is a dependent scope",
496 parser->scope, id, parser->scope);
500 When applied to the code, this might lead to:
507 being ``corrected'' to:
514 In this case, the correct thing to do is to add a trailing space after
518 gcc_rich_location richloc (loc);
519 // OK: note that here we have a trailing space
520 richloc.add_fixit_insert_before ("typename ");
521 error_at (&richloc, "need %<typename%> before %<%T::%E%> because "
522 "%qT is a dependent scope",
523 parser->scope, id, parser->scope);
527 leading to this corrected code:
533 @subsubsection Express deletion in terms of deletion, not replacement
535 It's best to express deletion suggestions in terms of deletion fix-it
536 hints, rather than replacement fix-it hints. For example, consider this:
539 auto_diagnostic_group d;
540 gcc_rich_location richloc (location_of (retval));
541 tree name = DECL_NAME (arg);
542 richloc.add_fixit_replace (IDENTIFIER_POINTER (name));
543 warning_at (&richloc, OPT_Wredundant_move,
544 "redundant move in return statement");
548 which is intended to e.g.@: replace a @code{std::move} with the underlying
552 return std::move (retval);
558 where the change has been expressed as replacement, replacing
559 with the name of the declaration.
560 This works for simple cases, but consider this case:
563 #ifdef SOME_CONFIG_FLAG
564 # define CONFIGURY_GLOBAL global_a
566 # define CONFIGURY_GLOBAL global_b
571 return std::move (CONFIGURY_GLOBAL /* some comment */);
576 The above implementation erroneously strips out the macro and the
577 comment in the fix-it hint:
580 return std::move (CONFIGURY_GLOBAL /* some comment */);
581 ~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
586 and thus this resulting code:
593 It's better to do deletions in terms of deletions; deleting the
594 @code{std::move (} and the trailing close-paren, leading to
598 return std::move (CONFIGURY_GLOBAL /* some comment */);
599 ~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
600 CONFIGURY_GLOBAL /* some comment */
604 and thus this result:
607 return CONFIGURY_GLOBAL /* some comment */;
611 Unfortunately, the pertinent @code{location_t} values are not always
614 @c the above was https://gcc.gnu.org/ml/gcc-patches/2018-08/msg01474.html
616 @subsubsection Multiple suggestions
618 In the rare cases where you need to suggest more than one mutually
619 exclusive solution to a problem, this can be done by emitting
620 multiple notes and calling
621 @code{rich_location::fixits_cannot_be_auto_applied} on each note's
622 @code{rich_location}. If this is called, then the fix-it hints in
623 the @code{rich_location} will be printed, but will not be added to
627 @node Guidelines for Options
628 @section Guidelines for Options
629 @cindex command-line options, guidelines for
630 @cindex options, guidelines for
631 @cindex guidelines for options