Aprenda Writing Clean and Stable Interfaces | Library Design Fundamentals

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.

Tudo estava claro?

Obrigado pelo seu feedback!

Seção 1. Capítulo 5

Pergunte à IA

Pergunte o que quiser ou experimente uma das perguntas sugeridas para iniciar nosso bate-papo

Deslize para mostrar o 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.