The ugliness of the windows API never ceases to amaze me. Functions with names like RtlDetermineDosPathNameType_U and return types like PCWSTR just make my eyes bleed.
My personal favorite is PCZZWSTR: a const pointer to a contiguous WCHAR array, where each substring is NUL-terminated, and the array itself is also terminated by a NUL. Thus (I assume) the ZZ--zero zero. I've only ever seen it used in the SHFILEOPSTRUCTW struct.
I feel like that construct, sometimes called "double-null terminated", is often inaccurately described.
I prefer to think of it as a contiguous block of null terminated strings terminated by an empty string. (Just as '\0' terminates a C string, the empty string terminates such a list.)
That's not an API. The article talks about some ntdll function, not supported by MS, and not documented by MS.
The ugliness might be deliberate, to make developers conclude "that must be some Windows internal BS, probably undocumented" when they see it in debugger, profiler or other places.
> The ugliness might be deliberate, to make developers conclude "that must be some Windows internal BS, probably undocumented" when they see it in debugger, profiler or other places.
Not at all. It is consistently named with internal NT APIs that are used like that intentionally. The people working at that layer follow such naming conventions without irony.
I know, but these are mostly not part of WinAPI either. The public API surface has very good names, WriteFile or CreateDirectory is IMO better than POSIX write or mkdir.
It definitely makes you wonder whether the 'E' key was broken on the machines at Bell Labs.
In all seriousness, Ken Thompson was asked what was the one thing we wanted to change in Unix if he could, and his answer was that he would spell "creat" with an "e"[1]. And funnily enough, he actually did in Go[2].
I don't know if they're good. WriteFile and CreateDirectory are fine, but when I think of the Windows API, I think of much longer function names. I had to use ConvertStringSecurityDescriptorToSecurityDescriptorA() once (and yeah, I had to use the ANSI version explicitly.) Another C/C++ developer might have called that function sec_sddl_to_desc(), which is much better IMO.
I know I'm probably in the minority, but I vastly prefer the long-form name in your example. Modern IDE's (especially Visual Studio with its Intellisense) can be incredible with their autocomplete, superseding the need for short-form obtuse acronym-laden function names that you need to remember.
So let's assume there's no time difference between writing the long or short form of that function. There's only one other direction to consider, which is reading.
Try to approach the following question without personal bias. If you have never worked with either API, which function name would be more self-explanatory for you? ConvertStringSecurityDescriptorToSecurityDescriptorA or sec_sddl_to_desc?
One problem is that there is no one Windows style. The style guidelines, if you can call them that, depend on a few things like age and provenance of the component (some examples of pieces with distinct styles: filesystem, registry, GDI, NT API, COM). And sometimes you see a mix of these, or a component come along with its own variation. (SDDL and other security APIs is a good example of a unique style.)
But sometimes people confuse unfamiliarity with ugliness, being bad or wrong, and having worked with a lot of these stuff I feel this is often a mischaracterization. Unfamiliarity doesn't always make it bad.
My personal favorite is PCZZWSTR: a const pointer to a contiguous WCHAR array, where each substring is NUL-terminated, and the array itself is also terminated by a NUL. Thus (I assume) the ZZ--zero zero. I've only ever seen it used in the SHFILEOPSTRUCTW struct.
That reads like one of the instruction mnemonics from https://twitter.com/x86instructions
>SHFILEOPSTRUCTW
now that takes the cake
Nah. That would be INITCOMMONCONTROLSEX. And the related LVM_SORTITEMSEX, DDSCAPSEX, and of course MPR_CREDENTIALSEX_0.
With Microsoft's use of ALLCAPS and using an "Ex" prefix, this was all but guaranteed…
How about SHITEMID in the shlwapi DLL? That's supposed to be SH-ITEM-ID.
if someone ever figures out the meaning of that phrase it's probably going to summon some cosmic horror that will be the end of us all
I've had some interesting experiences with SHFileOperationA on Wine. Star Citizen's updater wasn't working properly at one point due to it.
Multi-strings are also pretty common in the registry, see REG_MULTI_SZ.
I feel like that construct, sometimes called "double-null terminated", is often inaccurately described.
I prefer to think of it as a contiguous block of null terminated strings terminated by an empty string. (Just as '\0' terminates a C string, the empty string terminates such a list.)
That's not an API. The article talks about some ntdll function, not supported by MS, and not documented by MS.
The ugliness might be deliberate, to make developers conclude "that must be some Windows internal BS, probably undocumented" when they see it in debugger, profiler or other places.
> The ugliness might be deliberate, to make developers conclude "that must be some Windows internal BS, probably undocumented" when they see it in debugger, profiler or other places.
Not at all. It is consistently named with internal NT APIs that are used like that intentionally. The people working at that layer follow such naming conventions without irony.
> consistently named with internal NT APIs
I know, but these are mostly not part of WinAPI either. The public API surface has very good names, WriteFile or CreateDirectory is IMO better than POSIX write or mkdir.
My favorite Unix function has to be "creat". It doesn't even make sense given the limitations of the systems at the time.
It definitely makes you wonder whether the 'E' key was broken on the machines at Bell Labs.
In all seriousness, Ken Thompson was asked what was the one thing we wanted to change in Unix if he could, and his answer was that he would spell "creat" with an "e"[1]. And funnily enough, he actually did in Go[2].
[1]: https://unix.stackexchange.com/questions/10893/what-did-ken-... [2]: https://github.com/golang/go/commit/c90d392ce3d3203e0c32b3f9...
I don't know if they're good. WriteFile and CreateDirectory are fine, but when I think of the Windows API, I think of much longer function names. I had to use ConvertStringSecurityDescriptorToSecurityDescriptorA() once (and yeah, I had to use the ANSI version explicitly.) Another C/C++ developer might have called that function sec_sddl_to_desc(), which is much better IMO.
I know I'm probably in the minority, but I vastly prefer the long-form name in your example. Modern IDE's (especially Visual Studio with its Intellisense) can be incredible with their autocomplete, superseding the need for short-form obtuse acronym-laden function names that you need to remember.
So let's assume there's no time difference between writing the long or short form of that function. There's only one other direction to consider, which is reading.
Try to approach the following question without personal bias. If you have never worked with either API, which function name would be more self-explanatory for you? ConvertStringSecurityDescriptorToSecurityDescriptorA or sec_sddl_to_desc?
One problem is that there is no one Windows style. The style guidelines, if you can call them that, depend on a few things like age and provenance of the component (some examples of pieces with distinct styles: filesystem, registry, GDI, NT API, COM). And sometimes you see a mix of these, or a component come along with its own variation. (SDDL and other security APIs is a good example of a unique style.)
But sometimes people confuse unfamiliarity with ugliness, being bad or wrong, and having worked with a lot of these stuff I feel this is often a mischaracterization. Unfamiliarity doesn't always make it bad.