If you're not familiar with Visual Studio, that's a particular thing in Visual Studio. It's not only for a third party dox extractor (though it's used for that too), it's mainly useful for tooltips and IntelliSense help while you're coding.

For example, you're used to to IDEs which, when you type the name of a function, will automatically guide you through all the parameters to that function, right? Well, if you add those HTML comments in a particular format to your classes and functions in a Visual Studio project, then you get the same thing for your code's own internal functions. The format is larger and more complicated than what I provided in the oversimplified example. Here's a post about it: https://msdn.microsoft.com/en-us/magazine/dd722812.aspx

Regarding dox extractors like Doxygen... we're not documenting our code with any sort of automatic dox extractors that I know of. The code I'm talking about is all internal and doesn't have any formatted reference material (other than the self-referential stuff in the IDE as described above). Perhaps they're just making sure that if we ever DID use a third party dox extractor, then our code would be ready for it. Which is fine, but then, why the weird thing about no periods on inline comments? That's not part of any dox extractor that I know of.



Exactly, that's the thing that I'm not understanding and which trips me up. The fact that my company requires it is not in question, but since I know it's not a requirement for dox extraction, then, why deliberately subvert the English language like that? I was thinking that there's possibly some psychological reason for it, such as, I dunno, maybe trying to make the code flow more readable inside functions or something? I can't fathom it, but I'm wondering if there's some weird "school of thought" which espouses that style, and what its justification is, if it exists. Like, hungarian notation. That's got a whole thing behind it, it's there for a reason. I thought maybe this did too.