Library standardization

[Hans W. Uhlig]

e-t172 wrote:
> Koroskin Denis a écrit :
>> Current situation is, someone writes code, probably nice one, and it 
>> is added
>> to main trunk. Problem is, interface is implementation driven, not 
>> otherwise.
>> It is not discussed. And thats bad. Tests first, then code, Kent Beck 
>> said.
>> Of course, implementation can affect interface, but only after trial.
> 
> I have to agree on this one. As a side note, I definitely think we 
> *need* "real" header files (like .h files in C/C++), which separates the 
> API and his implementation. I see for advantages:
> 
> - Clearer presentation for the user of the API. The user is only 
> interested in the API, not in the implementation: if the user has to go 
> through the implementation to understand what the library does, it is a 
> result of bad documentation, and should be avoided. With header files, 
> all the information the user needs is put in one place, without the 
> "noise" of the implementation throughout the file.

This is true but why present code in the form of prototypes instead of 
auto built documentation ala Java. While the current JavaDocs lack some 
quality they do make up for a lot by auto generation documentation for 
just about everything. No headers necessary just an HTML file you can 
read and know everything public(and if the programmer did any 
documentation you know what it is, what it returns and what it does).
> 
> - More efficient. For example, on a Linux distro, if you want to write a 
> program using a library, you need to install the "dev" package of the 
> library, which only contains header files. There is no point of 
> including the implementation in the package, because it is not useful to 
> the user (and definitely not useful if you only want to compile a 
> project, not modify it). See the glibc as an example : if you needed the 
> entire source code of the glibc every time you wanted to compile a 
> program, this would have been a pure waste in terms of disk space and 
> compiler efficiency.

Why should You need extra code files for development. I have always 
found this annoying, you either need the library or you don't. If the 
library has API documentation, why would you need headers.

> 
> - Clear separation of "compiled" code and compile-time code. That is, if 
> a library provides "normal" code (accessed by an API) and compile-time 
> code (which is compiled in the application that uses the library, not in 
> the library itself), the two can be clearly distinguished: "normal" code 
> will only consist of declarations in the header file, while compile-time 
> code will be entirely defined in the header file. That way, the user 
> knows what IS in the library (the .a or .so file), and what will be 
> compiled in his application. (of course this is already possible, just 
> not as "clearly" for the user)

Ok, I can see this for fixed constants used by the library. Otherwise, 
why would you need them.

> 
> - Ability to distribute closed-source libraries. I'm against 
> closed-source libraries, but I know that a lot of people need them.

Again, I say API Docs!

> 
> Of course, header files also means additional maintenance issues. But it 
> shouldn't be too hard to write a program which automatically extract the 
> declarations and compile-time code out of a .d file, and use it to 
> generate a header file. This way, each time a .d file is modified, the 
> Makefile (or any other build system) would automatically trigger the 
> regeneration of the associated header file.

Self Built API Docs to the rescue!

> 
> P.S.: I'm not talking about .di files here. Last time I tried to 
> generate .di files, implementation was still included in them.