Designing APIs for Agents 7 days ago
Defaults are bad. Agents can be expected to read the documentation, register what good starting values are, and fill them all in, in place.
That is pretty bad, when you now need to look at this code, and you have 95% of the output being craft, but sometimes it isn't, and you need to understand the difference between each.
A great example of that is:
int fd = open("log.txt", O_RDONLY);
// 1. Manually build and initialize the Security Attributes structure
SECURITY_ATTRIBUTES sa;
sa.nLength = sizeof(SECURITY_ATTRIBUTES);
sa.lpSecurityDescriptor = NULL; // Explicitly no custom security descriptor (inherits default)
sa.bInheritHandle = FALSE; // Explicitly state this handle cannot be inherited by child processes
// 2. We need a handle for the template file parameter.
// Win32 requires this to be an active file handle opened with GENERIC_READ, or explicitly INVALID_HANDLE_VALUE.
HANDLE hTemplateFile = INVALID_HANDLE_VALUE;
// 3. Now we call CreateFile with every single parameter fully populated
HANDLE hFile = CreateFile(
"log.txt", // 1. lpFileName: The file we want to open
GENERIC_READ, // 2. dwDesiredAccess: Read-only access
FILE_SHARE_READ, // 3. dwShareMode: Prevents any other process from writing to it
&sa, // 4. lpSecurityAttributes: Pointer to our explicitly defined struct
OPEN_EXISTING, // 5. dwCreationDisposition: Only open if it already exists
FILE_ATTRIBUTE_NORMAL, // 6. dwFlagsAndAttributes: Normal file, no special caching or async flags
hTemplateFile // 7. hTemplateFile: Passing our explicit invalid handle instead of NULL
);
Did you catch the fact that this is blocking concurrent writers? Or that we expected the file to exist?
Or what about:
HFONT hFont = CreateFont(
12, 0, 0, 0, FW_NORMAL, TRUE, FALSE, FALSE,
DEFAULT_CHARSET, OUT_DEFAULT_PRECIS, CLIP_DEFAULT_PRECIS,
DEFAULT_QUALITY, DEFAULT_PITCH | FF_DONTCARE, "Arial"
);
const char* fontPath = "/usr/share/fonts/truetype/msttcorefonts/arial.ttf";
FT_New_Face(library, fontPath, 0, &face);
FT_Set_Pixel_Sizes(face, 0,16 );