AJ wrote:
"Steven Schveighoffer" <[email protected]> wrote in message
news:[email protected]...
On Wed, 21 Oct 2009 23:10:38 -0400, AJ <[email protected]> wrote:
"Steven Schveighoffer" <[email protected]> wrote in message
news:[email protected]...
On Wed, 21 Oct 2009 19:31:02 -0400, AJ <[email protected]> wrote:
"Steven Schveighoffer" <[email protected]> wrote in message
news:[email protected]...
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
