Page History

...

Noncompliant Code Example (interface)

It is not necessary to go beyond the standard C library to find examples of inconsistent interfaces. This is because that the standard library is a fusion of multiple different libraries with various styles and various levels of rigor.

For example, the fputs() defined in §7.19.7 is closely related to the fprintf() defined in §7.19.6. However, the fputs() has the file handle at the end and fprintf() at the beginning as shown by their function declarations.

int fputs(const char * restrict s, FILE * restrict stream);

int fprintf(FILE * restrict stream, const char * restrict format, ...);

The argument order can be easily rearranged using macros, for example:

#include <stdio.h>
#define fputs(X,Y) fputs(Y,X)

However, this makes the code difficult to read, for example, by causing confusion when moving between code that follows this convention and code that does not. In effect, it becomes impossible to modify an interface once that interface has been broadly adopted. Consequently, it is important to get the interface design right the first time.

Compliant Solution (interface)

The managed string library \[[Burch 06|AA. C References#Burch06]\] tries to be as consistent as possible, both internally, and with established conventions from the C standard library.  For example, functions that operate on a single instance of a {{string_m}}, but do modify the contents of the managed string, follow the pattern:

errno_t strlen_m(const string_m s, rsize_t *size);
errno_t isnull_m(const string_m s, _Bool *nullstr);
errno_t cgetstr_m(const string_m s, char **string);

where the first argument is declared as const string_m. For functions that implement a data abstraction (see DCL12-C. Implement abstract data types using opaque types), it is reasonable to define the handle for the data abstraction as the initial parameter.

Noncompliant Code Example (behavior)

...