Apprendre Writing Clean and Stable Interfaces

Designing a C++ library that is easy to use, robust, and maintainable requires careful attention to the public interface you expose. Your interface is the most visible part of your library: it is what every user interacts with, and it defines the contract between your code and its users. To write clean, minimal, and stable interfaces, follow these key guidelines:

Use descriptive, self-explanatory names for functions and parameters;
Keep your API minimal, exposing only what is necessary;
Document every public function and parameter clearly, as shown in the header file;
Prefer standard library types, such as std::vector, in your interface;
Use namespaces to avoid name collisions.

Don't

Use cryptic or abbreviated names that require guesswork;
Expose implementation details or unnecessary dependencies in your headers;
Leave functions or parameters undocumented;
Accept or return raw pointers without clear ownership documentation;
Change your public API without considering backward compatibility.

math_utils.h


              123456789101112131415161718192021222324252627282930313233343536
            
#pragma once

#include <vector>

/**
 * @brief Provides mathematical utility functions.
 *
 * All functions in this namespace are thread-safe and do not modify input data.
 */
namespace math_utils {

/**
 * @brief Computes the mean (average) of a vector of doubles.
 *
 * @param values A non-empty vector of double values.
 * @return The mean of the values. Returns 0.0 if the input vector is empty.
 *
 * Example:
 *     std::vector<double> nums = {1.0, 2.0, 3.0};
 *     double avg = math_utils::mean(nums); // avg == 2.0
 */
double mean(const std::vector<double>& values);

/**
 * @brief Computes the median of a vector of doubles.
 *
 * @param values A non-empty vector of double values.
 * @return The median value. Returns 0.0 if the input vector is empty.
 *
 * Example:
 *     std::vector<double> nums = {1.0, 3.0, 2.0};
 *     double med = math_utils::median(nums); // med == 2.0
 */
double median(const std::vector<double>& values);

} // namespace math_utils

By following these principles, you help ensure that your library is approachable, reliable, and easy to integrate into other projects.

Tout était clair ?

Merci pour vos commentaires !

Section 1. Chapitre 5

Demandez à l'IA

Posez n'importe quelle question ou essayez l'une des questions suggérées pour commencer notre discussion

Suggested prompts:

Can you list the key guidelines for designing a good C++ library interface?

Can you provide examples of clean and minimal C++ interfaces?

What are some common mistakes to avoid when designing a C++ library interface?

Glissez pour afficher le menu

Use descriptive, self-explanatory names for functions and parameters;
Keep your API minimal, exposing only what is necessary;
Document every public function and parameter clearly, as shown in the header file;
Prefer standard library types, such as std::vector, in your interface;
Use namespaces to avoid name collisions.