Idealy, I don't want to look at a header. I look at the document in hand that defines whatever's in the header.
I guess that's partly a philosophical issue, and partly a question of how your brain works.
Me, I can remember pretty much functions,and what they do. And I hate printed documentation, and electronic documentation just a bit less,
for use while coding. When I wanted to learn OpenGL, for example, I read the Reference Guide and the User's guide (the blue and red books) cover to cover several times. I can't imagine trying to lean OpenGL via API documentation. At the end of that I know I can call, say, Vertex3d, and the like, and what they do. But, what are the parameters to some of these things, and in what order? My brain is such that I'll never remember. I remember big picture stuff, but details escape me. I think a lot of programmers excel at remembering details, and thus a function like int foo (int, int, int) is perfectly readable. Me, i'm scratching my head! So, your method requires me to constantly be turning pages in a book, or searching in online documentation, having several windows open, refering back and forth, just to get the parameters to a function call right. (edit: not to mention the ability to just cut and paste from the header, and then just overtype the parameters with the variables/values you want).
On the other hand, in Visual Studio, if foo is declared Seconds foo (int distance, int speed), as soon as I type 'foo (' a little ballon pops up showing me that the first parameter is distance, not just 'int'. It also shows me the return type is Seconds. But even without that feature, having a being able to refer to a header file makes it easy for me to remember function names and parameter order with the mininum of fuss and page flipping. That equals not just speed, but accuracy. Moving eyes back and forth from book page to screen increases the odds of getting something wrong.
But all that depends on my coding style. I hate the Windows API, where a simply named function like
CreateFile can do things like: create a file, create a socket, create memory (memory mapped files with no physical file), etc. It does a dozen things. No one could reasonably use that without written documentation. To me that is horrible design, though there is a pretty good book out there describing how some of this came to be. In my world a function does one thing, and you generally don't use parameters to control 15 different modes. The way OpenGL handles state based programming is much better to my point of view, even if it is more verbose than the Microsoft way of handling things. 10 function calls to set the state, vs 10 parameters in a single function, all with multiple interpretations depending on what the other parameters are set to. You want documentation for all your code, and I want my code so singular in purpose that only the big picture stuff needs documentation at all.
To bring this back to
language (sorry wowbagger), C++ allows you to code things like this how you want - you aren't forced into a specific mode of expression. This is incredibly important in large programs where it usually makes sense to express yourself in several different modes (OO for GUI, functional for algorithmic work, templates for generic programming, etc). But to do so without creating a mess, style becomes incredibly important. It's not just style, it's about communicating to later coders exactly what you were thinking. If the language lets you hang yourself with parameter ordering, your style better make it hard to make a mistake, and take advantage of whatever IDE tools you have (like Visual Studio's autocomplete).
