On Wed, 21 Oct 2009 23:10:38 -0400, AJ <a...@nospam.net> wrote:
"Steven Schveighoffer" <schvei...@yahoo.com> wrote in message
news:op.u16j03t2eav...@localhost.localdomain...
On Wed, 21 Oct 2009 19:31:02 -0400, AJ <a...@nospam.net> wrote:
"Steven Schveighoffer" <schvei...@yahoo.com> wrote in message
news:op.u15929x0eav...@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
