![\"Lego](\"https:\/\/www.modernescpp.com\/wp-content\/uploads\/2017\/07\/Lego_dimensions.svg.png\")
<\/p>\nInterfaces are a contract between a service provider and a service consumer. The C++ Core Guidelines has 20 rules to make them suitable because “interfaces is probably the most important single aspect of code organization”.<\/p>\n
<\/p>\n
<\/p>\n
<\/p>\n
Before I dive into the rules, here is an overview of the 20 rules.<\/p>\n
Expects()<\/code> for expressing preconditions<\/a><\/li>\n- I.7: State postconditions<\/a><\/li>\n
- I.8: Prefer
Ensures()<\/code> for expressing postconditions<\/a><\/li>\n- I.9: If an interface is a template, document its parameters using concepts<\/a><\/li>\n
- I.10: Use exceptions to signal a failure to perform a required task<\/a><\/li>\n
- I.11: Never transfer ownership by a raw pointer (
T*<\/code>)<\/a><\/li>\n- I.12: Declare a pointer that must not be null as
not_null<\/code><\/a><\/li>\n- I.13: Do not pass an array as a single pointer<\/a><\/li>\n
- I.22: Avoid complex initialization of global objects<\/a><\/li>\n
- I.23: Keep the number of function arguments low<\/a><\/li>\n
- I.24: Avoid adjacent unrelated parameters of the same type<\/a><\/li>\n
- I.25: Prefer abstract classes as interfaces to class hierarchies<\/a><\/li>\n
- I.26: If you want a cross-compiler ABI, use a C-style subset<\/a><\/li>\n
- I.27: For stable library ABI, consider the Pimpl idiom<\/a><\/li>\n
- I.30: Encapsulate rule violations<\/a><\/li>\n<\/ul>\n
I will make my discussion of the rules not so elaborate because there are too many rules. My idea is to write in this post about the first ten rules and the next post about the remaining 10. So, let’s start.<\/p>\n
I.1: Make interfaces explicit<\/strong><\/h4>\nThis rule is about correctness and means: assumptions should be stated in an interface. Otherwise, they are easily overlooked and hard to test.<\/p>\n
\nint<\/span> round<\/span>(double<\/span> d)\r\n{\r\n return<\/span> (round_up) ?<\/span> ceil(d) :<\/span> d; \/\/ don't: \"invisible\" dependency<\/span>\r\n}\r\n<\/pre>\n<\/div>\n <\/p>\n
For example, the function round<\/span> does not express that its result depends on the invisible dependency round_up.<\/span><\/p>\nI.2: Avoid global variables<\/strong><\/h4>\nThis rule is obvious, but the emphasis lies on mutable global variables. Global constants are fine because they cannot introduce a dependency into the function and cannot be subject to race conditions.<\/p>\n
I.3: Avoid singletons<\/strong><\/h4>\nSingletons are global objects under the hood. Therefore, you should avoid them.<\/p>\n<\/p>\n
I.4: Make interfaces precisely and strongly typed<\/strong><\/h4>\nThe reason for this rule makes it clear: “Types are the simplest and best documentation, have a well-defined meaning, and are guaranteed to be checked at compile time.”<\/p>\n
Have a look at an example:<\/p>\n
\nvoid<\/span> draw_rect<\/span>(int<\/span>, int<\/span>, int<\/span>, int<\/span>); \/\/ great opportunities for mistakes<\/span>\r\ndraw_rect(p.x, p.y, 10<\/span>, 20<\/span>); \/\/ what does 10, 20 mean?<\/span>\r\n\r\nvoid<\/span> draw_rectangle<\/span>(Point top_left, Point bottom_right);\r\nvoid<\/span> draw_rectangle<\/span>(Point top_left, Size height_width);\r\n\r\ndraw_rectangle(p, Point{10<\/span>, 20<\/span>}); \/\/ two corners<\/span>\r\ndraw_rectangle(p, Size{10<\/span>, 20<\/span>}); \/\/ one corner and a (height, width) pair<\/span>\r\n<\/pre>\n<\/div>\n <\/p>\n
How easy is it to use the function draw_rect<\/span> incorrectly? Compare this to the function draw_rectangle.<\/span> The compiler guarantees that the argument is either a Point<\/span> or a Size<\/span> object.<\/p>\nYou should, therefore, look in your process of code improvement for functions with many built-in type arguments and, even worse, for functions that accept void*<\/span> as a parameter.<\/p>\nI.5: State preconditions (if any)<\/strong><\/h4>\nIf possible, preconditions such that x<\/span> in double sqrt(double x)<\/span> must be non-negative should be expressed as assertions.<\/p>\nExpects()<\/span> from the Guideline support library<\/a> (GSL) let you express your precondition directly.<\/p>\n\ndouble<\/span> sqrt<\/span>(double<\/span> x) { Expects(x >=<\/span> 0<\/span>); \/* ... *\/<\/span> }\r\n<\/pre>\n<\/div>\n <\/p>\n
Contracts, consisting of preconditions, postconditions, and assertions, may be part of the next C++20 standard. See the proposal p03801.pdf<\/a>.<\/p>\nI.6: Prefer Expects() for expressing preconditions<\/strong><\/h4>\nThat is similar to the previous rule, but the emphasis is on a different aspect. You should use Expects()<\/span> for expressing preconditions and not, for example, an if expression, a comment, or an assert()<\/span> statement. <\/p>\n\nint<\/span> area<\/span>(int<\/span> height, int<\/span> width)\r\n{\r\n Expects(height ><\/span> 0<\/span> &&<\/span> width ><\/span> 0<\/span>); \/\/ good<\/span>\r\n if<\/span> (height <=<\/span> 0<\/span> ||<\/span> width <=<\/span> 0<\/span>) my_error(); \/\/ obscure<\/span>\r\n \/\/ ...<\/span>\r\n}\r\n<\/pre>\n<\/div>\n <\/p>\n
The expression Expects()<\/span> is easier to spot and may be checkable by the upcoming C++20 standard.<\/p>\nI.7: State postconditions, I.8: Prefer Ensures() for expressing postconditions<\/strong><\/h4>\nFollowing the arguments of a function, you have to think about its results. Therefore, the postcondition rules are pretty similar to previous precondition rules.<\/p>\n
I.9: If an interface is a template, document its parameters using concepts<\/strong><\/h4>\nWe will get with high probability with C++20 concepts. Concepts are predicates on template parameters that can be evaluated at compile time. A concept may limit the set of arguments accepted as template parameters. I already wrote four posts about concepts<\/a>, because there is much more to concepts.<\/p>\nThe rule of the C++ Core Guidelines is quite easy. You should apply them.<\/p>\n
\ntemplate<\/span><<\/span>typename<\/span> Iter, typename<\/span> Val><\/span>\r\nrequires InputIterator<<\/span>Iter><\/span> &&<\/span> EqualityComparable<<\/span>ValueType<<\/span>Iter>><\/span>, Val><\/span>\r\nIter find(Iter first, Iter last, Val v)\r\n{\r\n \/\/ ...<\/span>\r\n}\r\n<\/pre>\n<\/div>\n <\/p>\n
The generic find<\/span> algorithm requires that the template parameter Iter<\/span> is an InputIterator<\/span> and the underlying value of the template parameter Iter<\/span> is EqualityComparable<\/span>. If you invoke the find<\/span> algorithm with a template argument that does not satisfy this requirement, you will get readable and easily understand<\/strong> the error message.<\/p>\nI. 10: Use exceptions to signal a failure to perform a required task<\/strong><\/h4>\nHere is why: “It should not be possible to ignore an error because that could leave the system or a computation in an undefined (or unexpected) state.”<\/p>\n
The rule provides a bad and a good example.<\/p>\n
\nint<\/span> printf<\/span>(const<\/span> char<\/span>*<\/span> ...); \/\/ bad: return negative number if output fails<\/span>\r\n\r\ntemplate<\/span> <<\/span>class<\/span> F<\/span>, class<\/span> ...Args<\/span>><\/span>\r\n\/\/ good: throw system_error if unable to start the new thread<\/span>\r\nexplicit<\/span> thread<\/span>(F&&<\/span> f, Args&&<\/span>... args);\r\n<\/pre>\n<\/div>\n <\/p>\n
In the wrong case, you can ignore the exception, and your program has undefined behavior.<\/p>\n
You should return a pair of values if you didn’t use exceptions. Thanks to C++17 feature structured binding<\/a>. You can do it quite elegantly.<\/p>\n\nauto<\/span> [val, error_code] =<\/span> do_something();\r\nif<\/span> (error_code ==<\/span> 0<\/span>) {\r\n \/\/ ... handle the error or exit ...<\/span>\r\n}\r\n\/\/ ... use val ...<\/span>\r\n<\/pre>\n<\/div>\n <\/p>\n
What’s next?<\/h2>\n