Hey everybody,
I am new to this forum as I am new to Handmade Hero. Just watching the Intro to C series and stumbled across something I even could remember from they days back when I was still coding in C(++). Nowadays I am more used to .NET (guess that's changing somehow atm... lol).
So what am I talking about?
First things first: If there was anyone already talking about SAL in this forum, please skip this post. I searched throughout the forum and didn't find anything in regards to Microsofts idea of a Sourcecode Annotation Language (SAL). So I decided to drop a little post about it.
Right at the beginning of the Intro to C series (as well as the beginning of the Main series), Casey copies a WinMain entry function right from MSDN and then deletes the _In_ macros. When I remember correctly, he doesn't go into details about what these macros really are (and are good for).
Basically it's about making code more "readable". Well, of course you could argue about whether or not annotating your code with somewhat obscure macros makes it more readable or not. However, here is a little example taken directly from MSDN:
To make is reasonable short: Since passing pointers could result in something happening to the variable only within the function as well as it could modify the original value (making it basically a return value), you couldn't really say what this function really does (only from reading this header).
This is where SAL drops in:
In this example, you can better tell what this function really does. Also, Microsofts compiler does "understand" this annotation language as well. That basically means that typical mistakes could be found at the compile time if SAL is used correctly.
So _In_ does really mean: "Data is passed to the called function, and is treated as read-only."
The fun part then is to use the Visual Studio Code Analysis Tool to possibly find code defects.
More on this can be found here:
https://msdn.microsoft.com/en-us/library/ms182032.aspx
Again: If this has been discussed elsewhere, just ignore this post. If the common perception of followers of this Tutorial series is to avoid proprietary techniques such as SAL, this is perfectly alright. I myself have no real experience in using SAL. :) However, it is a means of helping developers write quality code.
I am new to this forum as I am new to Handmade Hero. Just watching the Intro to C series and stumbled across something I even could remember from they days back when I was still coding in C(++). Nowadays I am more used to .NET (guess that's changing somehow atm... lol).
So what am I talking about?
First things first: If there was anyone already talking about SAL in this forum, please skip this post. I searched throughout the forum and didn't find anything in regards to Microsofts idea of a Sourcecode Annotation Language (SAL). So I decided to drop a little post about it.
Right at the beginning of the Intro to C series (as well as the beginning of the Main series), Casey copies a WinMain entry function right from MSDN and then deletes the _In_ macros. When I remember correctly, he doesn't go into details about what these macros really are (and are good for).
Basically it's about making code more "readable". Well, of course you could argue about whether or not annotating your code with somewhat obscure macros makes it more readable or not. However, here is a little example taken directly from MSDN:
1 2 3 4 5 | void * memcpy( void *dest, const void *src, size_t count ); |
To make is reasonable short: Since passing pointers could result in something happening to the variable only within the function as well as it could modify the original value (making it basically a return value), you couldn't really say what this function really does (only from reading this header).
This is where SAL drops in:
1 2 3 4 5 | void * memcpy( _Out_writes_bytes_all_(count) void *dest, _In_reads_bytes_(count) const void *src, size_t count ); |
In this example, you can better tell what this function really does. Also, Microsofts compiler does "understand" this annotation language as well. That basically means that typical mistakes could be found at the compile time if SAL is used correctly.
So _In_ does really mean: "Data is passed to the called function, and is treated as read-only."
The fun part then is to use the Visual Studio Code Analysis Tool to possibly find code defects.
More on this can be found here:
https://msdn.microsoft.com/en-us/library/ms182032.aspx
Again: If this has been discussed elsewhere, just ignore this post. If the common perception of followers of this Tutorial series is to avoid proprietary techniques such as SAL, this is perfectly alright. I myself have no real experience in using SAL. :) However, it is a means of helping developers write quality code.
It is an interesting suggestion. The non-platform code needs to be kept cross platform so, if we wanted to use this, it would have to be wrapped in macros. I believe clang also supports certain types of code annotations.
The fundamental question will be is the return on the investment associated with adding these to the code and the (possible) readability hit worth it in practice. The "const" thread basically boils down to this question as well.
The fundamental question will be is the return on the investment associated with adding these to the code and the (possible) readability hit worth it in practice. The "const" thread basically boils down to this question as well.
Edited by Patrick Lahey
on
Such annotations are not useful because they make the code more readable. Actually I find this hurts readability. But they are useful because they provide valuable information about how things are supposed to work and static analysis tools can work with them.
If I where to implement the memcpy function myself with those annotations like this
a static analyser could find my bug. Without those annotations it definitely wouldn't have enough information to do this.
If I where to implement the memcpy function myself with those annotations like this
1 2 3 4 5 6 7 8 9 10 11 12 | void * memcpy(
_Out_writes_bytes_all_(count) void *dest,
_In_reads_bytes_(count) const void *src,
size_t count
)
{
char *out = dest;
const char *in = src;
for (size_t i = 0; i <= count; i++) {
*out++ = *in++;
}
}
|
a static analyser could find my bug. Without those annotations it definitely wouldn't have enough information to do this.
I understand and agree with what you are saying. My point was that anything that adds extra development work and makes readability harder should be balanced against the expected real world benefit. The question is how often would adding these annotations actually catch a hard to find bug that a developer is likely to make and that static analysis cannot find without the extra annotation.
Is doing this going to make life better in practice rather than just in theory? There is no question, for example, that using const can prevent various types of mistakes. The question is are these mistakes you often make and do you find that it saves time in the end. Some people think const is worth it, others don't.
Is doing this going to make life better in practice rather than just in theory? There is no question, for example, that using const can prevent various types of mistakes. The question is are these mistakes you often make and do you find that it saves time in the end. Some people think const is worth it, others don't.
He said in the previous stream that he will clean up everything when it's all done. He also said something along the lines of
"if you are thinking about how clean your code should be, then you are programming the wrong way, you should be thinking about solving the problem first and then go back and clean it and make it readable"
"if you are thinking about how clean your code should be, then you are programming the wrong way, you should be thinking about solving the problem first and then go back and clean it and make it readable"
Edited by popcorn
on