"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? And you know that code folding of an implementation file cannot encompass the elements of hand-written header file. I may (and do) like to see things a certain way rather than the way IDE displays it (indeed, I use the IDE's code outlining mode for header files also many times). So, a code-folding editor is no replacement for header files (it does not eliminate the "need" for header files). But that's just my preference (to use header files). To each, their own. > > 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. 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. > 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).