I have become particularly fascinated with the current usage of this non-code code (non code as in, its not the language of the rest of the file), and the history of such non-code code.
In some cases this could be referred to as meta-programming, but I don't think that covers all the cases.
I've seen it used for many things, going back (in my experience) as far as the 80's with "Autodocs" in C comments, used to generate documentation, all the way up to very complex modern incarnations in interpreted languages like PHP where you have Annotations in comment blocks and they are used for documentation, for adding additional meaning where the PHP syntax falls short, and other kinds of "meta" data.
Its a big hodgepodge it seems. And I'm not sure yet how I feel about it. It seems somehow wrong. But yet I see great utility in it.
I am wondering what general term you would use to cover all these cases of non-code code that is in almost all of our code, and if there is any kind of definitive writings on the subject and its history, best practices, etc. If there is not, it interests me as something I would like to research and write myself.
For example, in PHP land, we have things like this:
/**
* This is a "docblock" and PHP can introspect on it
*
* The annotation below is common, and is used by processors to generate
* documentation. It can also be used by an IDE to provide hints while
* coding. Its also kinda redundant because in this case PHP is already
* providing the same information... it also has no effect on the code,
* unless some code is written to introspect on it and then do something.
*
* @param Request $request
*
* Another handy one, describing what is returned. PHP doesn't have
* a way to do this in the code, so this one is more useful.
*
* @return Response
*
* Here's some more annotations. The syntax is different, because, well,
* there's no restrictions...
*
* This is for generating Swagger API documentation. Cool huh? Again,
* it has no effect on the code. Period. Notice how it also specifies the
* type as a Response object (given that you understand this new syntax).
* Note also that this duplicates the functionality of @return above, but
* we need both because different tools are using them each.
*
* @SWG\Api(
* path="/gettax",
* description="Calculate tax",
* @SWG\Operation(
* method="POST",
* type="Response",
* @SWG\Parameter(paramType="body",required=true,type="GetTax")
* )
* )
*/
public function calc(Request $request) ....
At any rate, what I am seeing are so many tools that use these sorts of things, but there's a lot of overlap, and fragmentation. At least in PHP land. And I think back over many years of programming and I think this sort of stuff is nothing new.
I wanted to search on the subject but couldn't a good search term to get what I was looking for, which was some historical documentation on the origin of such methods, what has worked well or not over the years, best practices, etc. Is this all considered meta-programming?
What is the evolution of these things, do they become proper parts of the language at some point, or incorporated into new languages?
The subject interested me in general and I wondered if anybody else had written a definitive text on the subject?
It occurs to me that these things are really a form of Domain Specific Languages. Because the host language is not capable of expressing something, a DSL is used and embedded into the code (either in a comment or with some facility that the host language does support, like annotations) to express the other information you wish to associate with the code, without it necessarily having any effect on the code flow.
