No header files?

[AJ]

"Steven Schveighoffer" <schveiguy at yahoo.com> wrote in message 
news:op.u16mw4o6eav7ka at localhost.localdomain...
> 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.

That doesn't quite help me any though, now does it? Another non-reason why 
header files are obsolete?

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

Not nearly just that. For all the richness of everything contained therein: 
the blueprint (only), the brief documentation, the style, other things 
surely. Do I want to weed out the high level view or documentation from what 
is in the implementation file? No way! Documentation in the implementation 
file would be something like: "I used algorithm X instead of algorithm Y to 
implement this function because.." whereas documentation in a header file 
would be something like: "Class Z was developed to fullfill the following 
needs: ... and can be used where...".

>
>>
>>>
>>> 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?

Documentation is not the only value of header files. The constructs 
themselves are self-documenting. I don't want to read about something being 
a class, I want to see the class! Afterall, I'll be working with that in the 
code. Not some description of it in some paragraph. And if that auxiliary 
documentation has the class declaration, then what you ask? Well then it's 
basically a header file! (But without the value of being a high level design 
tool).

>  And a generated doc is just a different view of the  same data, so it's 
> more likely to be correct.

OK, enough of this now. I use header files for the reasons I mentioned. I've 
heard nothing to justify jettisoning them or even consider such.

>
>> 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,

Then you don't understand the concept of "blueprint".

> 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.

If there weren't header files, I would still write, say class, declarations 
and follow them with the out-of-line implementations. It gives me immediate 
grasp of what I am working with (would be a tad better without unnecessary 
semicolons all over the place too). Zero comments in a generated header, but 
a bigger issue for me is that not using header files means not developing in 
my chosen, well-thought-out way.

> The exact function signatures are copied from the  actual source, how is 
> that a brochure?

I was comparing header files with auxiliary documentation. Not generated 
headers.

>
>>
>>> 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,

No. They are only an artifact in a development style that choses to solely 
at the implementation level rather than at the specification and 
implementation levels.

>  auto-generated docs are an artifact.

Yes, because it assumes a development paradigm.

> If you have docs, you don't need headers,

Wrong. Nothing happens at the implementation level until the specification 
level has been (at least somewhat) defined. See? Get it? That's my 
development paradigm. You use yours, I'll use mine. OK?

> so your notion that more  artifacts are required is false.

Your notion of artifact is incorrect.

>  It takes me 1 second to generate the  docs

I start with "the docs". Has to be an egg before you can have a chicken. I 
don't build a car and then document it. I plan/design/specify it, THEN I 
build it.

> (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?

That's a non-issue.

> Don't you ever get tired of writing  every function signature twice?

I don't. I cut-n-paste, say a class definition, into the implementation 
file, get rid of those pesky semicolons and add the actual implementation 
code.

>
> Have you ever used generated docs?

That's not the way I develop code, nor a match for my thought processes: I 
plan/design/specify/architect and implement afterwards. (I draw a lot of 
boxes and arrows on paper (yes, paper!) before I actually write any header 
code).

> You might be surprised at how good they are.

N/A for me.