No header files?

[Steven Schveighoffer]

On Wed, 21 Oct 2009 23:10:38 -0400, AJ <aj at nospam.net> wrote:

>
> "Steven Schveighoffer" <schveiguy at yahoo.com> wrote in message
> news:op.u16j03t2eav7ka at localhost.localdomain...
>> On Wed, 21 Oct 2009 19:31:02 -0400, AJ <aj at nospam.net> wrote:
>>
>>>
>>> "Steven Schveighoffer" <schveiguy at yahoo.com> wrote in message
>>> news:op.u15929x0eav7ka at localhost.localdomain...
>>>
>>>> What happens (and being a  long-time C++ developer, I've had my fair
>>>> share
>>>> of experience with it) is  that the interface gets out of sync with  
>>>> the
>>>> implementation, so weird shit  happens.
>>>>
>>>> I even think d's "editable" interface files are suspect.  They can be
>>>> out
>>>> of sync with the object files, and then you have the same problem.   
>>>> The
>>>> best model by far is Java and C# where the object files *are* the
>>>> interface files.  Then you only have to worry about documentation  
>>>> being
>>>> out of sync.  But at least your programs don't crash randomly for no
>>>> reason because the docs are invalid.
>>>>
>>>> What I would suggest is creating stub functions via {} and then when  
>>>> you
>>>> go back to fill in the interface, fill in the {} area.  You get the  
>>>> same
>>>> effect.
>>>
>>> You lose the ability to use, say a class declaration, as the
>>> specification
>>> (at least without a sophisitcated, code-folding/code-formatting IDE).
>>
>> What do you use, Notepad?  Even vi does this now.
>
> Oh, can you print that out for me so I can look it over on the train ride
> into work?

Sure.  But I just prefer to use my laptop when traveling.

>
> And you know that code folding of an implementation file cannot encompass
> the elements of hand-written header file.

You mean format styles?  Yeah, I guess, but generally the formatting of a  
doc generator is customizable to your liking, so you don't have to deal  
with another person's style if you are reading a header you didn't write.

> But that's just my preference (to use header files). To
> each, their own.

Indeed.

>
>>
>> In any case, I seldom refer to the source file when I can just look at  
>> the
>> docs generated from the comments.  If you aren't commenting your API,  
>> then
>> I'm not using your lib, so don't even suggest that header files *without
>> comments* are better than auto-generated docs.
>
> I never suggested that header files not have comments. But I was saying  
> that
> I use header files as the "answer book" in using code (aka,  
> "documentation")
> and also that header files can eliminate the need for auxiliary
> documentation.

With source and headers, you have 2 pieces.  With source and docs, you  
have 2 pieces.  Why would documentation be considered any more auxiliary  
than header files?  And a generated doc is just a different view of the  
same data, so it's more likely to be correct.

> Good thing for me that the IDEs open header files with a few
> clicks on the #include <myhdr.h> line huh. A header file is the real  
> thing,
> while auxiliary documentation describes the real thing. Software isn't  
> built
> with documentation. It's built with source code. Blueprints, not a  
> brochure.

I look at headers and source as 2 blueprints, of which one or both might  
not be correct, so there is more chance for error.  More places to  
maintain the exact same thing means more overhead, more

And suggesting auto-generated docs are any different than a header file is  
completely false.  The exact function signatures are copied from the  
actual source, how is that a brochure?

>
>> Header files with comments  are trivially transformed into  
>> auto-generated
>> docs (one-liner).
>
> Why would I want to do that (generate more artifacts) when it's  
> unnecessary?
> I use header files. I find much value in them and see no reason to stop
> using them (yes, even after the discussion in this thread and even with  
> D).

Again, header files are an artifact, auto-generated docs are an artifact.   
If you have docs, you don't need headers, so your notion that more  
artifacts are required is false.  It takes me 1 second to generate the  
docs (in fact, it takes me no time, since I have a svn trigger setup to  
generate them), how long does it take you to update your header file when  
you want to update a function/class?  Don't you ever get tired of writing  
every function signature twice?

Have you ever used generated docs?  You might be surprised at how good  
they are.

-Steve