No header files?

[Chris Nicholson-Sauls]

AJ wrote:
> "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.
> 
> 

For what its worth, I've always drawn diagrams and written flowcharts and all that happy 
fun time stuffy myself... the wife has whapped me many a time for muttering my way through 
an algorithm or a pipeline when I was supposed to be listening to her... From what I 
gather from this discussion, you and I actually have rather similar approaches.

That said, I've never written a header in D.  Model packages with only interfaces, 
occasionally.  Headers, no.  I plan it all out, hash out the implementation-free module, 
and when I'm ready I go back and flesh the little buggers out, in place.  And I've never 
looked back.

Not really arguing one way or the other, just adding my tuppence.

-- Chris Nicholson-Sauls