www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - No header files?

reply "AJ" <aj nospam.net> writes:
Since D has no header files, how does one create "a library" that another 
developer can use without exposing the implementation? 
Oct 21 2009
next sibling parent reply "Steven Schveighoffer" <schveiguy yahoo.com> writes:
On Wed, 21 Oct 2009 17:59:52 -0400, AJ <aj nospam.net> wrote:

 Since D has no header files, how does one create "a library" that another
 developer can use without exposing the implementation?

try dmd -H. .di files are D header files, basically used for the reason you specify. -Steve
Oct 21 2009
parent reply "AJ" <aj nospam.net> writes:
"Steven Schveighoffer" <schveiguy yahoo.com> wrote in message 
news:op.u157hfkveav7ka localhost.localdomain...
 On Wed, 21 Oct 2009 17:59:52 -0400, AJ <aj nospam.net> wrote:

 Since D has no header files, how does one create "a library" that another
 developer can use without exposing the implementation?

try dmd -H. .di files are D header files, basically used for the reason you specify.

OK, so header files can be generated. The thing is though, when I am designing at the code level, I start with the declarations (such as class data members and methods) and do the implementation (or one can hand it off to someone else) afterwards. That serves as the "blue print" for further development and remains as first level of documentation as well. Working with just "implementation files" seems to be putting the cart before the horse. While eliminating something unnecessary is something to strive for, I don't think header files are unnecessary in the development process (i.e., I don't think that relegating them to just the situation given with my OP is good, exactly for the reasons of usefullness I gave).
Oct 21 2009
next sibling parent reply BCS <none anon.com> writes:
Hello aJ,

 "Steven Schveighoffer" <schveiguy yahoo.com> wrote in message
 news:op.u157hfkveav7ka localhost.localdomain...
 
 On Wed, 21 Oct 2009 17:59:52 -0400, AJ <aj nospam.net> wrote:
 
 Since D has no header files, how does one create "a library" that
 another developer can use without exposing the implementation?
 

.di files are D header files, basically used for the reason you specify.

designing at the code level, I start with the declarations (such as class data members and methods) and do the implementation (or one can hand it off to someone else) afterwards.

As it happens, .di files are just .d files that by convention only contain the interface. You can declare a class in a .d file and not give bodies for its methods and you won't get errors till link time, just like in C.
 That serves as the "blue
 print" for further development and remains as first level of
 documentation as well. Working with just "implementation files" seems
 to be putting the cart before the horse. While eliminating something
 unnecessary is something to strive for, I don't think header files are
 unnecessary in the development process (i.e., I don't think that
 relegating them to just the situation given with my OP is good,
 exactly for the reasons of usefullness I gave).

I'm not sure what use you are seeing for them. As far as documentation goes, In the cases where I don't care about the implementation, I'd rather see some kind of extracted, generated documentation rather than a header file. The only argument I see for a header/implementation split is if you need to put part of a class in one file and part in another and I think that is a very weak case.
Oct 21 2009
parent reply "AJ" <aj nospam.net> writes:
"BCS" <none anon.com> wrote in message 
news:a6268ffbae78cc207990f9b394 news.digitalmars.com...
 Hello aJ,

 "Steven Schveighoffer" <schveiguy yahoo.com> wrote in message
 news:op.u157hfkveav7ka localhost.localdomain...

 On Wed, 21 Oct 2009 17:59:52 -0400, AJ <aj nospam.net> wrote:

 Since D has no header files, how does one create "a library" that
 another developer can use without exposing the implementation?

.di files are D header files, basically used for the reason you specify.

designing at the code level, I start with the declarations (such as class data members and methods) and do the implementation (or one can hand it off to someone else) afterwards.

As it happens, .di files are just .d files that by convention only contain the interface. You can declare a class in a .d file and not give bodies for its methods and you won't get errors till link time, just like in C.
 That serves as the "blue
 print" for further development and remains as first level of
 documentation as well. Working with just "implementation files" seems
 to be putting the cart before the horse. While eliminating something
 unnecessary is something to strive for, I don't think header files are
 unnecessary in the development process (i.e., I don't think that
 relegating them to just the situation given with my OP is good,
 exactly for the reasons of usefullness I gave).

I'm not sure what use you are seeing for them.

The 2 that I gave were: 1. Serves as a "blueprint" (or skeleton) for further development. 2. Serves as "documentation" for usage or for evaluation-for-purpose (suitability). (1) is "working at a higher level (designing vs. implenting) and perhaps even separating much of the design work from the implementation work (i.e., separate individuals or teams working on one or the other). (2) eliminates the need for secondary documentation (for well-designed code). I think of secondary documentation as the detailed description of how something works. Prior to consulting such, I'd want to know "what" something is, and something like a class declaration gives me that information immediately, without reading paragraphs of text. For example, you can describe "car" to me, but it would be much easier to just show me one.
 As far as documentation goes, In the cases where I don't care about the 
 implementation, I'd rather see some kind of extracted, generated 
 documentation rather than a header file.

Class Shape { void Draw(); } What more do you need to know usually?
 The only argument I see for a header/implementation split is if you need 
 to put part of a class in one file and part in another and I think that is 
 a very weak case.

Oct 21 2009
next sibling parent reply BCS <none anon.com> writes:
Hello aJ,

 "BCS" <none anon.com> wrote in message
 news:a6268ffbae78cc207990f9b394 news.digitalmars.com...
 
 I'm not sure what use you are seeing for them.
 

1. Serves as a "blueprint" (or skeleton) for further development.

.d files can do this
 2. Serves as "documentation" for usage or for
 evaluation-for-purpose
 (suitability).

I will hold that the full source or "webpage like" documentation will do better in all cases than a header file. The first for where the details matter and the second for all other cases because it can contain anything the header can and is not bound by language constraints.
 (1) is "working at a higher level (designing vs. implenting) and
 perhaps even separating much of the design work from the
 implementation work (i.e., separate individuals or teams working on
 one or the other). (2) eliminates the need for secondary documentation
 (for well-designed code). I think of secondary documentation as the
 detailed description of how something works. Prior to consulting such,
 I'd want to know "what" something is, and something like a class
 declaration gives me that information immediately, without reading
 paragraphs of text. For example, you can describe "car" to me, but it
 would be much easier to just show me one.
 

As said above, you can declare a class without implementing it in the current system as well as progamaticly extract what you are asking for in whatever format you want.
 As far as documentation goes, In the cases where I don't care about
 the implementation, I'd rather see some kind of extracted, generated
 documentation rather than a header file.
 

{ void Draw(); } What more do you need to know usually?

Some times I'd like some comments/verbiage. Some times I'd like exactly that but with better formatting. The point is that if you want to start by coding that up, you can with the current system. If you have a full program and you want that, you can generate it from the full program with the current system. I have yet to see anything you have asked for that the current system can't give you. It just doesn't give it to you in exactly the same way C does.
Oct 21 2009
parent reply "AJ" <aj nospam.net> writes:
"BCS" <none anon.com> wrote in message 
news:a6268ffbb078cc2081280f1286 news.digitalmars.com...
 Hello aJ,

 "BCS" <none anon.com> wrote in message
 news:a6268ffbae78cc207990f9b394 news.digitalmars.com...

 I'm not sure what use you are seeing for them.

1. Serves as a "blueprint" (or skeleton) for further development.

.d files can do this
 2. Serves as "documentation" for usage or for
 evaluation-for-purpose
 (suitability).

I will hold that the full source or "webpage like" documentation will do better in all cases than a header file. The first for where the details matter and the second for all other cases because it can contain anything the header can and is not bound by language constraints.

We'll have to agree to disagree on that. Eliminating headers but requiring a "webpage", is "robbing Peter to pay Paul".
 (1) is "working at a higher level (designing vs. implenting) and
 perhaps even separating much of the design work from the
 implementation work (i.e., separate individuals or teams working on
 one or the other). (2) eliminates the need for secondary documentation
 (for well-designed code). I think of secondary documentation as the
 detailed description of how something works. Prior to consulting such,
 I'd want to know "what" something is, and something like a class
 declaration gives me that information immediately, without reading
 paragraphs of text. For example, you can describe "car" to me, but it
 would be much easier to just show me one.

As said above, you can declare a class without implementing it in the current system as well as progamaticly extract what you are asking for in whatever format you want.

So, it would appear, that if I am to write in D, I will be writing .di files just like I write .h files in C/C++. OK.
 As far as documentation goes, In the cases where I don't care about
 the implementation, I'd rather see some kind of extracted, generated
 documentation rather than a header file.

{ void Draw(); } What more do you need to know usually?

Some times I'd like some comments/verbiage.

Well of course header files will have comments. The thing is though, tomes of documentation are not necessary you have header files. And what are the chances that the documentation will be in synch with the code if the documentation is external? Much better chance of that if the header file IS the documentation and the code is crafted such that it needs very little doc.
 Some times I'd like exactly that but with better formatting.

Seems like the exception rather than the common case. It depends on the coding style I guess. Certainly the STL header files are useless as any kind of documentation, that I grant you. But I'd consider that style of coding the exceptional case also.
 The point is that if you want to start by coding that up, you can with the 
 current system.

OK, noted. If I ever write any D, that will be my preferred style.
 If you have a full program and you want that, you can generate it from the 
 full program with the current system.

I won't be using that feature.
 I have yet to see anything you have asked for that the current system 
 can't give you. It just doesn't give it to you in exactly the same way C 
 does.

Apparently it does! No?
Oct 21 2009
parent reply BCS <none anon.com> writes:
Hello aJ,

 "BCS" <none anon.com> wrote in message
 news:a6268ffbb078cc2081280f1286 news.digitalmars.com...
 
 I will hold that the full source or "webpage like" documentation will
 do better in all cases than a header file. The first for where the
 details matter and the second for all other cases because it can
 contain anything the header can and is not bound by language
 constraints.
 

requiring a "webpage", is "robbing Peter to pay Paul".

Note that I'm assuming the avalability of a tool (like DMD has) to automaticly generate sutch a document.
 (1) is "working at a higher level (designing vs. implenting) and
 perhaps even separating much of the design work from the
 implementation work (i.e., separate individuals or teams working on
 one or the other). (2) eliminates the need for secondary
 documentation (for well-designed code). I think of secondary
 documentation as the detailed description of how something works.
 Prior to consulting such, I'd want to know "what" something is, and
 something like a class declaration gives me that information
 immediately, without reading paragraphs of text. For example, you
 can describe "car" to me, but it would be much easier to just show
 me one.
 

current system as well as progamaticly extract what you are asking for in whatever format you want.

files just like I write .h files in C/C++. OK.

Nope. The only time you should ever write a .di file by hand is as bindings for a non D codebase. .di files that describe something written in D should be auto generated. If you want to sketch out an interface and now and implement it later, I'd expect both to be done in a .d file (just replace the function bodies with ';')
 What more do you need to know usually?


tomes of documentation are not necessary you have header files. And what are the chances that the documentation will be in synch with the code if the documentation is external? Much better chance of that if the header file IS the documentation and the code is crafted such that it needs very little doc.

Or even better, the code file has both the documentation source and the implementation source and you have a tool that can use that one file to generate the final documentation in a nicer format. BTW, the same argument for not having the documentation be in a different file from the header also holds for not having the interface definition be in a different file from the implementation.
 Some times I'd like exactly that but with better formatting.
 

the coding style I guess. Certainly the STL header files are useless as any kind of documentation, that I grant you. But I'd consider that style of coding the exceptional case also.

Even the best code editor I've ever seen doesn't come close to the readability that a halfway well done web page has. Try putting nice tables in your header files. Try adding clickable hyperlinks, always up to date tables of contents and indexes. A good tool will give you that and more for lest effort than it takes to keep the comment wrapping at 80 columns.
 The point is that if you want to start by coding that up, you can
 with the current system.
 

 If you have a full program and you want that, you can generate it
 from the full program with the current system.
 

 I have yet to see anything you have asked for that the current system
 can't give you. It just doesn't give it to you in exactly the same
 way C does.
 


It does what? C generally uses hand written interface and implementation files. D has either; a hand written implementation file and a auto generated interface file, only the implementation file or a hand written interface file and a non-D implementation. Doesn't look like what C does or am I totally lost on what you are looking for?
Oct 22 2009
parent reply "AJ" <aj nospam.net> writes:
"BCS" <none anon.com> wrote in message 
news:a6268ffbc118cc2111f7478a3e news.digitalmars.com...
 Hello aJ,

 "BCS" <none anon.com> wrote in message
 news:a6268ffbb078cc2081280f1286 news.digitalmars.com...

 I will hold that the full source or "webpage like" documentation will
 do better in all cases than a header file. The first for where the
 details matter and the second for all other cases because it can
 contain anything the header can and is not bound by language
 constraints.

requiring a "webpage", is "robbing Peter to pay Paul".

Note that I'm assuming the avalability of a tool (like DMD has) to automaticly generate sutch a document.

Doesn't fit my development process.
 (1) is "working at a higher level (designing vs. implenting) and
 perhaps even separating much of the design work from the
 implementation work (i.e., separate individuals or teams working on
 one or the other). (2) eliminates the need for secondary
 documentation (for well-designed code). I think of secondary
 documentation as the detailed description of how something works.
 Prior to consulting such, I'd want to know "what" something is, and
 something like a class declaration gives me that information
 immediately, without reading paragraphs of text. For example, you
 can describe "car" to me, but it would be much easier to just show
 me one.

current system as well as progamaticly extract what you are asking for in whatever format you want.

files just like I write .h files in C/C++. OK.

Nope.

Uh huh!!
The only time you should ever write a .di file by hand is as bindings for a 
non D codebase.

Now we're going in circles (in this thread). It has been said that I don't have to change my development process to use D (I use C++ now).
 .di files that describe something written in D should be auto generated.

You say tomatoe, I say tomato.
 If you want to sketch out an interface and now and implement it later, I'd 
 expect both to be done in a .d file (just replace the function bodies with 
 ';')

 What more do you need to know usually?


tomes of documentation are not necessary you have header files. And what are the chances that the documentation will be in synch with the code if the documentation is external? Much better chance of that if the header file IS the documentation and the code is crafted such that it needs very little doc.

Or even better, the code file has both the documentation source and the implementation source and you have a tool that can use that one file to generate the final documentation in a nicer format. BTW, the same argument for not having the documentation be in a different file from the header also holds for not having the interface definition be in a different file from the implementation.

No need to try to convince me to adopt a new development process. Save your breath.
 The point is that if you want to start by coding that up, you can
 with the current system.

 If you have a full program and you want that, you can generate it
 from the full program with the current system.

 I have yet to see anything you have asked for that the current system
 can't give you. It just doesn't give it to you in exactly the same
 way C does.


It does what?

Give it in exactly the same way. (Allows me to develop headers first and potentially hand those off to someone else to flesh out).
 C generally uses hand written interface and implementation files. D has 
 either; a hand written implementation file and a auto generated interface 
 file, only the implementation file or a hand written interface file and a 
 non-D implementation.

 Doesn't look like what C does or am I totally lost on what you are looking 
 for?

Now I'm unsure about .di files. Are they like .h files or not? Does D have classes that are like C++ classes that can be declared in .di files and are not just "interfaces"? What is the definition of "interface" in D? I think in C++ isms and generally accepted OO terminology for that kind of thing, but I don't know D-isms at this time (for the most part).
Oct 22 2009
next sibling parent reply =?UTF-8?B?IkrDqXLDtG1lIE0uIEJlcmdlciI=?= <jeberger free.fr> writes:
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: quoted-printable

AJ wrote:
 Now I'm unsure about .di files. Are they like .h files or not? Does D h=

 classes that are like C++ classes that can be declared in .di files and=

 not just "interfaces"? What is the definition of  "interface" in D? I t=

 in C++ isms and generally accepted OO terminology for that kind of thin=

 but I don't know D-isms at this time (for the most part).
=20

there is no way to ensure that they remain in sync with the code.=20 OTOH if you use the automatic generation then there is no way to=20 control what exactly is put in it (a lot of code gets put in the .di=20 file so that the compiler will be able to inline it where it is used). Jerome --=20 mailto:jeberger free.fr http://jeberger.free.fr Jabber: jeberger jabber.fr
Oct 22 2009
parent reply "AJ" <aj nospam.net> writes:
It's blank.  Dunno what to tell ya. I'll try Quotefix and maybe that will 
help.

""Jérôme M. Berger"" <jeberger free.fr> wrote in message 
news:hbqf8a$1sb8$3 digitalmars.com... 
Oct 22 2009
parent "AJ" <aj nospam.net> writes:
AJ wrote:
 It's blank.  Dunno what to tell ya. I'll try Quotefix and maybe that
 will help.

Nope, didn't help. I can see your posts though if I look at the details via the properties (OE).
 ""Jérôme M. Berger"" <jeberger free.fr> wrote in message
 news:hbqf8a$1sb8$3 digitalmars.com...

Oct 22 2009
prev sibling parent BCS <none anon.com> writes:
Hello aJ,

 "BCS" <none anon.com> wrote in message
 news:a6268ffbc118cc2111f7478a3e news.digitalmars.com...
 
 Note that I'm assuming the avalability of a tool (like DMD has) to
 automaticly generate sutch a document.
 


Just add A flag to your build and you got it.
 So, it would appear, that if I am to write in D, I will be writing
 .di files just like I write .h files in C/C++. OK.
 



If you write D the way the people who developed it intend you to write it, you will never hand write a .di file for d code.
 
 The only time you should ever write a .di file by hand is as bindings
 for a non D codebase.
 

don't have to change my development process to use D (I use C++ now).

/I/ never said that
 Now I'm unsure about .di files. Are they like .h files or not? Does D
 have classes that are like C++ classes that can be declared in .di
 files and are not just "interfaces"? What is the definition of
 "interface" in D? I think in C++ isms and generally accepted OO
 terminology for that kind of thing, but I don't know D-isms at this
 time (for the most part).
 

FWIW, I'm not talking about language constructs like classes and interfaces. I'm talking about interfaces as in the thing the compiler needs so that it can error check code not defined in the current module. What a .di file is is a .d file with everything striped out that DMD wouldn't look at anyway if it was imported from another module.
Oct 22 2009
prev sibling next sibling parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Wed, Oct 21, 2009 at 08:05:46PM -0500, AJ wrote:
 Well of course header files will have comments. The thing is though, tomes 
 of documentation are not necessary you have header files. And what are the 
 chances that the documentation will be in synch with the code if the 
 documentation is external? Much better chance of that if the header file IS 
 the documentation and the code is crafted such that it needs very little 
 doc.

That's what ddoc is all about. http://www.digitalmars.com/d/2.0/ddoc.html /// Some little documentation int someFunction(int a, int b) { implementation } All in one file. -- Adam D. Ruppe http://arsdnet.net
Oct 21 2009
parent reply "AJ" <aj nospam.net> writes:
"Adam D. Ruppe" <destructionator gmail.com> wrote in message 
news:mailman.226.1256173717.20261.digitalmars-d puremagic.com...
 On Wed, Oct 21, 2009 at 08:05:46PM -0500, AJ wrote:
 Well of course header files will have comments. The thing is though, 
 tomes
 of documentation are not necessary you have header files. And what are 
 the
 chances that the documentation will be in synch with the code if the
 documentation is external? Much better chance of that if the header file 
 IS
 the documentation and the code is crafted such that it needs very little
 doc.

That's what ddoc is all about. http://www.digitalmars.com/d/2.0/ddoc.html

Even that is over-kill when formal documentation is not required. "one size fits all" hardly ever does (never?). Sure, if you're Microsoft, you need to formally document in great detail the API. But most development does not require the large-scale solutions. A lot of times (I'd say the common case) does not require external formal documentation. While these kinds of things may be nice in certain situations, they don't wipe out everything else once they are created. My way of thinking is such that eliminates the need for yet another programming task while your's seems to be to take that task for granted and automate it. That's fine, there's no one correct answer other than do it the way you like to. I won't be ditching header files.
 /// Some little documentation
 int someFunction(int a, int b) { implementation }

 All in one file.

Oct 21 2009
parent reply "Nick Sabalausky" <a a.a> writes:
"AJ" <aj nospam.net> wrote in message news:hbof8k$edb$1 digitalmars.com...
 "Adam D. Ruppe" <destructionator gmail.com> wrote in message 
 news:mailman.226.1256173717.20261.digitalmars-d puremagic.com...
 On Wed, Oct 21, 2009 at 08:05:46PM -0500, AJ wrote:
 Well of course header files will have comments. The thing is though, 
 tomes
 of documentation are not necessary you have header files. And what are 
 the
 chances that the documentation will be in synch with the code if the
 documentation is external? Much better chance of that if the header file 
 IS
 the documentation and the code is crafted such that it needs very little
 doc.

That's what ddoc is all about. http://www.digitalmars.com/d/2.0/ddoc.html

Even that is over-kill when formal documentation is not required. "one size fits all" hardly ever does (never?). Sure, if you're Microsoft, you need to formally document in great detail the API. But most development does not require the large-scale solutions. A lot of times (I'd say the common case) does not require external formal documentation. While these kinds of things may be nice in certain situations, they don't wipe out everything else once they are created. My way of thinking is such that eliminates the need for yet another programming task while your's seems to be to take that task for granted and automate it. That's fine, there's no one correct answer other than do it the way you like to. I won't be ditching header files.
 /// Some little documentation
 int someFunction(int a, int b) { implementation }

 All in one file.


If you want to manually write a separate redundant file with just declarations before writing the implementation, no one's stopping you.
Oct 21 2009
parent reply "AJ" <aj nospam.net> writes:
"Nick Sabalausky" <a a.a> wrote in message 
news:hbontv$uqh$1 digitalmars.com...
 "AJ" <aj nospam.net> wrote in message news:hbof8k$edb$1 digitalmars.com...
 "Adam D. Ruppe" <destructionator gmail.com> wrote in message 
 news:mailman.226.1256173717.20261.digitalmars-d puremagic.com...
 On Wed, Oct 21, 2009 at 08:05:46PM -0500, AJ wrote:
 Well of course header files will have comments. The thing is though, 
 tomes
 of documentation are not necessary you have header files. And what are 
 the
 chances that the documentation will be in synch with the code if the
 documentation is external? Much better chance of that if the header 
 file IS
 the documentation and the code is crafted such that it needs very 
 little
 doc.

That's what ddoc is all about. http://www.digitalmars.com/d/2.0/ddoc.html

Even that is over-kill when formal documentation is not required. "one size fits all" hardly ever does (never?). Sure, if you're Microsoft, you need to formally document in great detail the API. But most development does not require the large-scale solutions. A lot of times (I'd say the common case) does not require external formal documentation. While these kinds of things may be nice in certain situations, they don't wipe out everything else once they are created. My way of thinking is such that eliminates the need for yet another programming task while your's seems to be to take that task for granted and automate it. That's fine, there's no one correct answer other than do it the way you like to. I won't be ditching header files.
 /// Some little documentation
 int someFunction(int a, int b) { implementation }

 All in one file.


If you want to manually write a separate redundant file with just declarations before writing the implementation, no one's stopping you.

You sound angry that your feature is not a fit for my development process. "jump in and start coding algorithms" is not an acceptable development method in my book.
Oct 21 2009
next sibling parent reply "Nick Sabalausky" <a a.a> writes:
"AJ" <aj nospam.net> wrote in message news:hbosh1$17l4$1 digitalmars.com...
 "Nick Sabalausky" <a a.a> wrote in message 
 news:hbontv$uqh$1 digitalmars.com...
 If you want to manually write a separate redundant file with just 
 declarations before writing the implementation, no one's stopping you.

You sound angry that your feature is not a fit for my development process. "jump in and start coding algorithms" is not an acceptable development method in my book.

Don't put words in my mouth.
Oct 21 2009
parent reply "AJ" <aj nospam.net> writes:
"Nick Sabalausky" <a a.a> wrote in message 
news:hboum3$1bhi$1 digitalmars.com...
 "AJ" <aj nospam.net> wrote in message 
 news:hbosh1$17l4$1 digitalmars.com...
 "Nick Sabalausky" <a a.a> wrote in message 
 news:hbontv$uqh$1 digitalmars.com...
 If you want to manually write a separate redundant file with just 
 declarations before writing the implementation, no one's stopping you.

You sound angry that your feature is not a fit for my development process. "jump in and start coding algorithms" is not an acceptable development method in my book.

Don't put words in my mouth.

I wasn't. I was telling you what I parsed your verbage into (and I'm correct 99% of the time) and gave you back some of your own medicine.
Oct 22 2009
next sibling parent reply "Nick Sabalausky" <a a.a> writes:
"AJ" <aj nospam.net> wrote in message news:hbp6ka$1uv9$1 digitalmars.com...
 "Nick Sabalausky" <a a.a> wrote in message 
 news:hboum3$1bhi$1 digitalmars.com...
 "AJ" <aj nospam.net> wrote in message 
 news:hbosh1$17l4$1 digitalmars.com...
 "Nick Sabalausky" <a a.a> wrote in message 
 news:hbontv$uqh$1 digitalmars.com...
 If you want to manually write a separate redundant file with just 
 declarations before writing the implementation, no one's stopping you.

You sound angry that your feature is not a fit for my development process. "jump in and start coding algorithms" is not an acceptable development method in my book.

Don't put words in my mouth.

I wasn't. I was telling you what I parsed your verbage into (and I'm correct 99% of the time) and gave you back some of your own medicine.

superdan, is that you?
Oct 22 2009
parent "AJ" <aj nospam.net> writes:
"Nick Sabalausky" <a a.a> wrote in message 
news:hbpa7q$27ro$1 digitalmars.com...
 "AJ" <aj nospam.net> wrote in message 
 news:hbp6ka$1uv9$1 digitalmars.com...
 "Nick Sabalausky" <a a.a> wrote in message 
 news:hboum3$1bhi$1 digitalmars.com...
 "AJ" <aj nospam.net> wrote in message 
 news:hbosh1$17l4$1 digitalmars.com...
 "Nick Sabalausky" <a a.a> wrote in message 
 news:hbontv$uqh$1 digitalmars.com...
 If you want to manually write a separate redundant file with just 
 declarations before writing the implementation, no one's stopping you.

You sound angry that your feature is not a fit for my development process. "jump in and start coding algorithms" is not an acceptable development method in my book.

Don't put words in my mouth.

I wasn't. I was telling you what I parsed your verbage into (and I'm correct 99% of the time) and gave you back some of your own medicine.

superdan, is that you?

No. And tomorrow (later today after I get done sleeping), I'm going to do more coding and less newsgrouping! Goodnight.
Oct 22 2009
prev sibling parent downs <default_357-line yahoo.de> writes:
AJ wrote:
 "Nick Sabalausky" <a a.a> wrote in message 
 news:hboum3$1bhi$1 digitalmars.com...
 "AJ" <aj nospam.net> wrote in message 
 news:hbosh1$17l4$1 digitalmars.com...
 "Nick Sabalausky" <a a.a> wrote in message 
 news:hbontv$uqh$1 digitalmars.com...
 If you want to manually write a separate redundant file with just 
 declarations before writing the implementation, no one's stopping you.

process. "jump in and start coding algorithms" is not an acceptable development method in my book.


I wasn't. I was telling you what I parsed your verbage into (and I'm correct 99% of the time) and gave you back some of your own medicine.

As an independent observer: your parser is broken.
Oct 22 2009
prev sibling parent reply BCS <none anon.com> writes:
Hello aJ,

 You sound angry that your feature is not a fit for my development
 process.

I think the frustration here is that you seem to be saying that you can't do something in D that you want to do but we have yet to figure out what it is. Every thing I have seen you ask for is already possible with D as it is now (including hand writing both the header and implementation in different files with all the potential for errors and duplication of work that D tries avoid).
 "jump in and start coding algorithms" is not an acceptable
 development method in my book.
 

In my experience, where you can't just start writing code, you can't just start writing headers either. I'd start on a white board or word and once stuff is designed there, I'd implement stubs with enough comment to know what they are supposed to do. In this mode, the header files would just be busy work.
Oct 22 2009
parent reply "AJ" <aj nospam.net> writes:
"BCS" <none anon.com> wrote in message 
news:a6268ffbc158cc2111f3e3b246 news.digitalmars.com...
 Hello aJ,

 You sound angry that your feature is not a fit for my development
 process.

I think the frustration here is that you seem to be saying that you can't do something in D that you want to do but we have yet to figure out what it is.

No, not at all. I realized far back in this thread that I can develop in D as I do now in C++ (header files come first). The thread went on with people trying to convince me how wrong that process is (?).
 Every thing I have seen you ask for is already possible with D as it is 
 now (including hand writing both the header and implementation in 
 different files with all the potential for errors and duplication of work 
 that D tries avoid).

 "jump in and start coding algorithms" is not an acceptable
 development method in my book.

In my experience, where you can't just start writing code, you can't just start writing headers either. I'd start on a white board or word and once stuff is designed there, I'd implement stubs with enough comment to know what they are supposed to do. In this mode, the header files would just be busy work.

I've noted in a previous thread that actual coding (header or source file) is not the first step in my process. The source code isn't even the important part, though perhaps the most pesky part.
Oct 22 2009
next sibling parent reply BCS <none anon.com> writes:
Hello aJ,

 "BCS" <none anon.com> wrote in message
 news:a6268ffbc158cc2111f3e3b246 news.digitalmars.com...
 
 Hello aJ,
 
 You sound angry that your feature is not a fit for my development
 process.
 

can't do something in D that you want to do but we have yet to figure out what it is.

in D as I do now in C++ (header files come first). The thread went on with people trying to convince me how wrong that process is (?).

I'm still not clear on exactly what you plan on doing. If you plan on generating the function prototypes in a .d file and filling out the bodies later, go for it. If you plan on hand writing the .di file and then writing the implementation in a .d file... ah... that's a bad idea (for one there is no error checking between a .di file and the implementation file).
Oct 22 2009
parent reply "AJ" <aj nospam.net> writes:
"BCS" <none anon.com> wrote in message 
news:a6268ffbc7d8cc213dc5feed9c news.digitalmars.com...
 Hello aJ,

 "BCS" <none anon.com> wrote in message
 news:a6268ffbc158cc2111f3e3b246 news.digitalmars.com...

 Hello aJ,

 You sound angry that your feature is not a fit for my development
 process.

can't do something in D that you want to do but we have yet to figure out what it is.

in D as I do now in C++ (header files come first). The thread went on with people trying to convince me how wrong that process is (?).

I'm still not clear on exactly what you plan on doing.

"Traditional" (read C/C++ like) software development.
 If you plan on generating the function prototypes

Nope. I plan on hand-crafting header files before I create any implementation files.
  in a .d file and filling out the bodies later, go for it.

Oh, by "generating" (bad choice of word), you meant "writing". Yes I do.
 If you plan on hand writing the .di file

Ooops! No I don't! Yes, I will be "modeling" via header files.
  and then writing the implementation in a .d file... ah... that's a bad 
 idea (for one there is no error checking between a .di file and the 
 implementation file).

Now you get what I was saying above! Yes? Ohhhh! You mean that .di files are NOT like C++ header files. I think I see what you mean. Other people have told me I could work the same way I currently do in C++, but apparently, there is a big paradigm shift in the development model between C++ and D. I never even considered that D meant changing the process. Very, very good info I am getting here. Maybe I asked too soon about a D IDE, as I can't invest as much time (brainpower actually) as required to get my mind around the "whole smear" right now. I may just concentrate on select features of D for now (as I have been doing).
Oct 22 2009
next sibling parent BCS <none anon.com> writes:
Hello aJ,

 "BCS" <none anon.com> wrote in message
 news:a6268ffbc7d8cc213dc5feed9c news.digitalmars.com...

 and then writing the implementation in a .d file... ah... that's a
 bad idea (for one there is no error checking between a .di file and
 the implementation file).
 

Ohhhh! You mean that .di files are NOT like C++ header files. I think I see what you mean. Other people have told me I could work the same way I currently do in C++, but apparently, there is a big paradigm shift in the development model between C++ and D. I never even considered that D meant changing the process. Very, very good info I am getting here. Maybe I asked too soon about a D IDE, as I can't invest as much time (brainpower actually) as required to get my mind around the "whole smear" right now. I may just concentrate on select features of D for now (as I have been doing).

Maybe some background on how import works: The line "import foo;" causes DMD to go looking for the file "foo.di" if it can't find it, it then goes looking for "foo.d" if it finds either, it then goes on and parses the file for the info it needs. IIRC, once it has located the file DMD doesn't care which it is, the processing is the same. When DMD is compiling foo.d it never even looks for foo.di and in fact if you compile foo.d and bar.d (where bar.d imports foo) DMD might well be free to never even look at foo.di even if it exists. DMD assumes that x.di and x.d are identical in every way that it cares about. D goes off the point that the ONLY reason that C doesn't extract the info from other .c files and instead use a preprocessor to tack a pile of files together, was that back in the good old days, computers just didn't have enough memory to do that.
Oct 22 2009
prev sibling next sibling parent Jacob Carlborg <doob me.com> writes:
On 10/23/09 05:08, AJ wrote:
 "BCS"<none anon.com>  wrote in message
 news:a6268ffbc7d8cc213dc5feed9c news.digitalmars.com...
 Hello aJ,

 "BCS"<none anon.com>  wrote in message
 news:a6268ffbc158cc2111f3e3b246 news.digitalmars.com...

 Hello aJ,

 You sound angry that your feature is not a fit for my development
 process.

can't do something in D that you want to do but we have yet to figure out what it is.

in D as I do now in C++ (header files come first). The thread went on with people trying to convince me how wrong that process is (?).

I'm still not clear on exactly what you plan on doing.

"Traditional" (read C/C++ like) software development.
 If you plan on generating the function prototypes

Nope. I plan on hand-crafting header files before I create any implementation files.
   in a .d file and filling out the bodies later, go for it.

Oh, by "generating" (bad choice of word), you meant "writing". Yes I do.
 If you plan on hand writing the .di file

Ooops! No I don't! Yes, I will be "modeling" via header files.
   and then writing the implementation in a .d file... ah... that's a bad
 idea (for one there is no error checking between a .di file and the
 implementation file).

Now you get what I was saying above! Yes? Ohhhh! You mean that .di files are NOT like C++ header files. I think I see what you mean. Other people have told me I could work the same way I currently do in C++, but apparently, there is a big paradigm shift in the development model between C++ and D. I never even considered that D meant changing the process. Very, very good info I am getting here. Maybe I asked too soon about a D IDE, as I can't invest as much time (brainpower actually) as required to get my mind around the "whole smear" right now. I may just concentrate on select features of D for now (as I have been doing).

I can't see why it's so important for your development process to have the declaration and implementation of classes and methods in separate files. If you want a person to develop the declaration and another to do the implementation why not just use a .d file and write the methods with empty bodies and then hand over the file to the person how will do the implementation?
Oct 23 2009
prev sibling parent reply "AJ" <aj nospam.net> writes:
"Leandro Lucarella" <llucax gmail.com> wrote in message 
news:20091023125658.GA23090 llucax.com.ar...
 AJ, el 22 de octubre a las 22:08 me escribiste:
 I'm still not clear on exactly what you plan on doing.

"Traditional" (read C/C++ like) software development.
 If you plan on generating the function prototypes

Nope. I plan on hand-crafting header files before I create any implementation files.
  in a .d file and filling out the bodies later, go for it.

Oh, by "generating" (bad choice of word), you meant "writing". Yes I do.
 If you plan on hand writing the .di file

Ooops! No I don't! Yes, I will be "modeling" via header files.

May I suggest something? If you want to "model via header files", write .d files with just declarations (skip implementations). You'll end up with hand written .di (headers) files, but in a .d files, so you can still automatically generate .di files from it. Use the .d files as an import in other modules (i.e., don't provide hand written .di files only). Then, when you want to start implementing your "model", just add the bodies to the functions in the "modeled" .d file. The effect in the development process is the same as hand writing .h files and progressively fill the .cpp files with the implementation, but you are doing all the work in just *one* place (the .cpp/.d files) and generating the headers files (.h/.di) from that. What problems do you find in that scheme? -- Leandro Lucarella (AKA luca) http://llucax.com.ar/ ---------------------------------------------------------------------- GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145 104C 949E BFB6 5F5A 8D05) ---------------------------------------------------------------------- Soy como una mosca, parada en el agua. Y vos sos un transatlántico, querés nadar a mi lado. Y me estás ahogando.

I'm convinced: D is not me.
Oct 23 2009
parent "AJ" <aj nospam.net> writes:
"Leandro Lucarella" <llucax gmail.com> wrote in message 
news:20091024182205.GA28347 llucax.com.ar...
 AJ, el 24 de octubre a las 01:44 me escribiste:
 "Leandro Lucarella" <llucax gmail.com> wrote in message
 news:20091023125658.GA23090 llucax.com.ar...
 AJ, el 22 de octubre a las 22:08 me escribiste:
 I'm still not clear on exactly what you plan on doing.


May I suggest something? If you want to "model via header files", write .d files with just declarations (skip implementations). You'll end up with hand written .di (headers) files, but in a .d files, so you can still automatically generate .di files from it. Use the .d files as an import in other modules (i.e., don't provide hand written .di files only). Then, when you want to start implementing your "model", just add the bodies to the functions in the "modeled" .d file. The effect in the development process is the same as hand writing .h files and progressively fill the .cpp files with the implementation, but you are doing all the work in just *one* place (the .cpp/.d files) and generating the headers files (.h/.di) from that. What problems do you find in that scheme?

I'm convinced: D is not me.

My question was honest, I'm really curious about what problems do see.

While I was being just a tad facetious, I was not nearly entirely so being. I cannot make an assessment of the D development process in depth at this time (but I'm hardly new at SW dev and can eval things at a high level and determine whether or not they have value for me (for example, if it's not a curly brace language, it's not for me)). I have no issue with my C++ process (and I even like it over the D one). To each there own. I need to get some software out the door, and one doesn't do that by destroying the old factory and putting up a new one.
Oct 25 2009
prev sibling next sibling parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Thu, Oct 22, 2009 at 10:08:08PM -0500, AJ wrote:
 I'm still not clear on exactly what you plan on doing.

"Traditional" (read C/C++ like) software development.

I remember many years ago, when I first saw D, I dismissed it for exactly this header file reason. I went to digitalmars.com to grab the updated DMC and 16 bit development extensions - yes, the Digital Mars C++ compiler _to this day_ still can put out 16 bit DOS executables! Very cool - anyway and I saw this D language thing. I clicked on it and glanced through the docs. But at the time, I dismissed it, due to one line: import std.stdio; I looked at that and said "ugh just another stupid Java" got DMC++ and carried on. Worst. Mistake. Ever. So a while later, I find myself back at digitalmars.com for no particular reason - by this time, my DOS development days were pretty well over, but I checked out the site for old time's sake. This time, I said "oh what the hell" and actually wrote a little D code. Didn't take long to fall in love. Some things are different, yes, but they are different *for the better*. D is simply outstanding and gets better each month. It is scary taking that first step, but once you do, you won't want to look back. Now, let me tell you a similar story about Walter Bright's EMPIRE: THE WARGAME OF THE CENTURY.... -- Adam D. Ruppe http://arsdnet.net
Oct 22 2009
parent "AJ" <aj nospam.net> writes:
Adam D. Ruppe wrote:
 On Thu, Oct 22, 2009 at 10:08:08PM -0500, AJ wrote:
 I'm still not clear on exactly what you plan on doing.

"Traditional" (read C/C++ like) software development.

I remember many years ago, when I first saw D, I dismissed it for exactly this header file reason.

OK, noted.
 I went to digitalmars.com to grab the updated DMC and 16 bit
 development extensions - yes, the Digital Mars C++ compiler _to this
 day_ still can put out 16 bit DOS executables! Very cool - anyway and
 I saw this D language thing.

 I clicked on it and glanced through the docs. But at the time, I
 dismissed it, due to one line:

 import std.stdio;

That import statement DOES interest me. I only have my goof-off time to research long-term things though. To me, it looks akin to getting an interface pointer (I only know C++, keep in mind) from a DLL. If so (which it probably isn't), I associate that with high-level packaging/deployment of production libraries, and separate from low-level library development.
Oct 22 2009
prev sibling next sibling parent Leandro Lucarella <llucax gmail.com> writes:
AJ, el 22 de octubre a las 22:08 me escribiste:
 I'm still not clear on exactly what you plan on doing.

"Traditional" (read C/C++ like) software development.
 If you plan on generating the function prototypes

Nope. I plan on hand-crafting header files before I create any implementation files.
  in a .d file and filling out the bodies later, go for it.

Oh, by "generating" (bad choice of word), you meant "writing". Yes I do.
 If you plan on hand writing the .di file

Ooops! No I don't! Yes, I will be "modeling" via header files.

May I suggest something? If you want to "model via header files", write .d files with just declarations (skip implementations). You'll end up with hand written .di (headers) files, but in a .d files, so you can still automatically generate .di files from it. Use the .d files as an import in other modules (i.e., don't provide hand written .di files only). Then, when you want to start implementing your "model", just add the bodies to the functions in the "modeled" .d file. The effect in the development process is the same as hand writing .h files and progressively fill the .cpp files with the implementation, but you are doing all the work in just *one* place (the .cpp/.d files) and generating the headers files (.h/.di) from that. What problems do you find in that scheme? -- Leandro Lucarella (AKA luca) http://llucax.com.ar/ ---------------------------------------------------------------------- GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145 104C 949E BFB6 5F5A 8D05) ---------------------------------------------------------------------- Soy como una mosca, parada en el agua. Y vos sos un transatlántico, querés nadar a mi lado. Y me estás ahogando.
Oct 23 2009
prev sibling parent Leandro Lucarella <llucax gmail.com> writes:
AJ, el 24 de octubre a las 01:44 me escribiste:
 "Leandro Lucarella" <llucax gmail.com> wrote in message 
 news:20091023125658.GA23090 llucax.com.ar...
 AJ, el 22 de octubre a las 22:08 me escribiste:
 I'm still not clear on exactly what you plan on doing.


May I suggest something? If you want to "model via header files", write .d files with just declarations (skip implementations). You'll end up with hand written .di (headers) files, but in a .d files, so you can still automatically generate .di files from it. Use the .d files as an import in other modules (i.e., don't provide hand written .di files only). Then, when you want to start implementing your "model", just add the bodies to the functions in the "modeled" .d file. The effect in the development process is the same as hand writing .h files and progressively fill the .cpp files with the implementation, but you are doing all the work in just *one* place (the .cpp/.d files) and generating the headers files (.h/.di) from that. What problems do you find in that scheme?

I'm convinced: D is not me.

My question was honest, I'm really curious about what problems do see. -- Leandro Lucarella (AKA luca) http://llucax.com.ar/ ---------------------------------------------------------------------- GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145 104C 949E BFB6 5F5A 8D05) ---------------------------------------------------------------------- CAYO HUGO CONZI --- TENIA PUESTA PELUCA -- Crónica TV
Oct 24 2009
prev sibling parent "Steven Schveighoffer" <schveiguy yahoo.com> writes:
On Thu, 22 Oct 2009 06:16:50 -0400, AJ <aj nospam.net> wrote:

 No. And tomorrow (later today after I get done sleeping), I'm going to do
 more coding and less newsgrouping! Goodnight.

Oh thank god. (Yes, keep replying, I'm going to see how long I can keep you away from critical header development) -Steve
Oct 22 2009
prev sibling next sibling parent reply "AJ" <aj nospam.net> writes:
"Steven Schveighoffer" <schveiguy yahoo.com> wrote in message 
news:op.u15929x0eav7ka localhost.localdomain...
 On Wed, 21 Oct 2009 18:16:48 -0400, AJ <aj nospam.net> wrote:

 "Steven Schveighoffer" <schveiguy yahoo.com> wrote in message
 news:op.u157hfkveav7ka localhost.localdomain...
 On Wed, 21 Oct 2009 17:59:52 -0400, AJ <aj nospam.net> wrote:

 Since D has no header files, how does one create "a library" that 
 another
 developer can use without exposing the implementation?

try dmd -H. .di files are D header files, basically used for the reason you specify.

OK, so header files can be generated. The thing is though, when I am designing at the code level, I start with the declarations (such as class data members and methods) and do the implementation (or one can hand it off to someone else) afterwards. That serves as the "blue print" for further development and remains as first level of documentation as well. Working with just "implementation files" seems to be putting the cart before the horse. While eliminating something unnecessary is something to strive for, I don't think header files are unnecessary in the development process (i.e., I don't think that relegating them to just the situation given with my OP is good, exactly for the reasons of usefullness I gave).

Separating interface from implementation is good -- but not if you have to repeat the interface (as you do with C++ or C).

I wouldn't use the term "interface" in this context for it has other meaning in OO.
 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).
Oct 21 2009
next sibling parent reply Walter Bright <newshound1 digitalmars.com> writes:
AJ wrote:
 You lose the ability to use, say a class declaration, as the specification 
 (at least without a sophisitcated, code-folding/code-formatting IDE). 

Just change "class" to "interface" and you're good to go.
Oct 21 2009
parent reply "AJ" <aj nospam.net> writes:
"Walter Bright" <newshound1 digitalmars.com> wrote in message 
news:hbo7fa$316k$2 digitalmars.com...
 AJ wrote:
 You lose the ability to use, say a class declaration, as the 
 specification (at least without a sophisitcated, 
 code-folding/code-formatting IDE).

Just change "class" to "interface" and you're good to go.

Seems "apples and oranges" to me. "class declaration" can have data members while "interface" can't. I mean, "my concept of it". I don't know what definitions D has of those things. In C++, I use interfaces where appropriate (say, where usage outside of a given library/subsystem is anticipated/desired), but for most purposes (say, within a given library/subsystem), I want a full class declaration (with data members etc). When I think "interface", I think "pure abstract base class" and is something strictly behavioral. When thinking "class" or "struct", I think first of the data members, something more nominal ("noun-ish").
Oct 21 2009
parent reply Walter Bright <newshound1 digitalmars.com> writes:
AJ wrote:
 "Walter Bright" <newshound1 digitalmars.com> wrote in message 
 news:hbo7fa$316k$2 digitalmars.com...
 AJ wrote:
 You lose the ability to use, say a class declaration, as the 
 specification (at least without a sophisitcated, 
 code-folding/code-formatting IDE).


Seems "apples and oranges" to me. "class declaration" can have data members while "interface" can't.

It's usually considered good style to keep your data members hidden from users. Interfaces do that nicely.
 I mean, "my concept of it". I don't know what 
 definitions D has of those things. In C++, I use interfaces where 
 appropriate (say, where usage outside of a given library/subsystem is 
 anticipated/desired), but for most purposes (say, within a given 
 library/subsystem), I want a full class declaration (with data members etc). 
 When I think "interface", I think "pure abstract base class" and is 
 something strictly behavioral. When thinking "class" or "struct", I think 
 first of the data members, something more nominal ("noun-ish"). 

If you're exposing data members to all the users, then you might as well expose the function bodies, too, because the benefits of hiding the implementation are already mostly gone.
Oct 22 2009
parent "AJ" <aj nospam.net> writes:
"Walter Bright" <newshound1 digitalmars.com> wrote in message 
news:hbp309$1nb9$1 digitalmars.com...
 AJ wrote:
 "Walter Bright" <newshound1 digitalmars.com> wrote in message 
 news:hbo7fa$316k$2 digitalmars.com...
 AJ wrote:
 You lose the ability to use, say a class declaration, as the 
 specification (at least without a sophisitcated, 
 code-folding/code-formatting IDE).


Seems "apples and oranges" to me. "class declaration" can have data members while "interface" can't.

It's usually considered good style to keep your data members hidden from users.

That's an incomplete thought. You are assuming a certain scenario perhaps. It would be seemingly (for lack of any agreement on the definition of "users" and the context) an extreme position to take otherwise. And no, I don't want to entertain or tangent to OO 101 dialog/discussion/debate either thank you.
 Interfaces do that nicely.

 I mean, "my concept of it". I don't know what definitions D has of those 
 things. In C++, I use interfaces where appropriate (say, where usage 
 outside of a given library/subsystem is anticipated/desired), but for 
 most purposes (say, within a given library/subsystem), I want a full 
 class declaration (with data members etc). When I think "interface", I 
 think "pure abstract base class" and is something strictly behavioral. 
 When thinking "class" or "struct", I think first of the data members, 
 something more nominal ("noun-ish").

If you're exposing data members to all the users, then you might as well expose the function bodies, too, because the benefits of hiding the implementation are already mostly gone.

There's no sense in discussing it in such a general or dogmatic way.
Oct 22 2009
prev sibling parent reply "AJ" <aj nospam.net> writes:
"Steven Schveighoffer" <schveiguy yahoo.com> wrote in message 
news:op.u16j03t2eav7ka localhost.localdomain...
 On Wed, 21 Oct 2009 19:31:02 -0400, AJ <aj nospam.net> wrote:

 "Steven Schveighoffer" <schveiguy yahoo.com> wrote in message
 news:op.u15929x0eav7ka 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).
Oct 21 2009
parent reply "AJ" <aj nospam.net> writes:
"Steven Schveighoffer" <schveiguy yahoo.com> wrote in message 
news:op.u16mw4o6eav7ka localhost.localdomain...
 On Wed, 21 Oct 2009 23:10:38 -0400, AJ <aj nospam.net> wrote:

 "Steven Schveighoffer" <schveiguy yahoo.com> wrote in message
 news:op.u16j03t2eav7ka localhost.localdomain...
 On Wed, 21 Oct 2009 19:31:02 -0400, AJ <aj nospam.net> wrote:

 "Steven Schveighoffer" <schveiguy yahoo.com> wrote in message
 news:op.u15929x0eav7ka 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.
Oct 21 2009
parent Chris Nicholson-Sauls <ibisbasenji gmail.com> writes:
AJ wrote:
 "Steven Schveighoffer" <schveiguy yahoo.com> wrote in message 
 news:op.u16mw4o6eav7ka localhost.localdomain...
 On Wed, 21 Oct 2009 23:10:38 -0400, AJ <aj nospam.net> wrote:

 "Steven Schveighoffer" <schveiguy yahoo.com> wrote in message
 news:op.u16j03t2eav7ka localhost.localdomain...
 On Wed, 21 Oct 2009 19:31:02 -0400, AJ <aj nospam.net> wrote:

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

specification (at least without a sophisitcated, code-folding/code-formatting IDE).


into work?


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.


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.

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.

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.


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

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


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
Oct 21 2009
prev sibling parent reply =?UTF-8?B?IkrDqXLDtG1lIE0uIEJlcmdlciI=?= <jeberger free.fr> writes:
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: quoted-printable

Steven Schveighoffer wrote:
 On Wed, 21 Oct 2009 18:16:48 -0400, AJ <aj nospam.net> wrote:
=20
 "Steven Schveighoffer" <schveiguy yahoo.com> wrote in message
 news:op.u157hfkveav7ka localhost.localdomain...
 On Wed, 21 Oct 2009 17:59:52 -0400, AJ <aj nospam.net> wrote:

 Since D has no header files, how does one create "a library" that=20
 another
 developer can use without exposing the implementation?

try dmd -H. .di files are D header files, basically used for the reason you speci=



 OK, so header files can be generated. The thing is though, when I am
 designing at the code level, I start with the declarations (such as cl=


 data members and methods) and do the implementation (or one can hand=20
 it off
 to someone else) afterwards. That serves as the "blue print" for furth=


 development and remains as first level of documentation as well. Worki=


 with just "implementation files" seems to be putting the cart before t=


 horse. While eliminating something unnecessary is something to strive =


 for, I
 don't think header files are unnecessary in the development process=20
 (i.e., I
 don't think that relegating them to just the situation given with my=20
 OP is
 good, exactly for the reasons of usefullness I gave).

Separating interface from implementation is good -- but not if you have=

 to repeat the interface (as you do with C++ or C).  What happens (and=20
 being a long-time C++ developer, I've had my fair share of experience=20
 with it) is that the interface gets out of sync with the implementation=

 so weird shit happens.
=20

files. Just include the .h and the compiler will barf if they don't=20 match... Jerome --=20 mailto:jeberger free.fr http://jeberger.free.fr Jabber: jeberger jabber.fr
Oct 22 2009
next sibling parent reply "AJ" <aj nospam.net> writes:
""Jérôme M. Berger"" <jeberger free.fr> wrote in message 
news:hbq76m$18in$1 digitalmars.com...

All your posts are showing up empty here Jerome. 
Oct 22 2009
parent reply "Nick Sabalausky" <a a.a> writes:
"Denis Koroskin" <2korden gmail.com> wrote in message 
news:op.u17vung8o7cclz korden-pc...
On Thu, 22 Oct 2009 23:42:06 +0400, AJ <aj nospam.net> wrote:

 ""Jérôme M. Berger"" <jeberger free.fr> wrote in message
 news:hbq76m$18in$1 digitalmars.com...

 All your posts are showing up empty here Jerome.

Nope, they are perfectly fine. Try configuring your Thunderbird/Mnenhy or use alternative NNTP client.

They show up as attachments for me.
Oct 22 2009
next sibling parent reply Walter Bright <newshound1 digitalmars.com> writes:
Denis Koroskin wrote:
 On Fri, 23 Oct 2009 05:20:04 +0400, Nick Sabalausky <a a.a> wrote:
 
 "Denis Koroskin" <2korden gmail.com> wrote in message
 news:op.u17vung8o7cclz korden-pc...
 On Thu, 22 Oct 2009 23:42:06 +0400, AJ <aj nospam.net> wrote:

 ""Jérôme M. Berger"" <jeberger free.fr> wrote in message
 news:hbq76m$18in$1 digitalmars.com...

 All your posts are showing up empty here Jerome.

Nope, they are perfectly fine. Try configuring your Thunderbird/Mnenhy or use alternative NNTP client.

They show up as attachments for me.

Looks like Outlook Express is crappy too :) Try Opera

I'm using thunderbird, and things work fine.
Oct 22 2009
parent =?UTF-8?B?IkrDqXLDtG1lIE0uIEJlcmdlciI=?= <jeberger free.fr> writes:
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: quoted-printable

Walter Bright wrote:
 Denis Koroskin wrote:
 On Fri, 23 Oct 2009 05:20:04 +0400, Nick Sabalausky <a a.a> wrote:

 "Denis Koroskin" <2korden gmail.com> wrote in message
 news:op.u17vung8o7cclz korden-pc...
 On Thu, 22 Oct 2009 23:42:06 +0400, AJ <aj nospam.net> wrote:
 ""J=C3=A9r=C3=B4me M. Berger"" <jeberger free.fr> wrote in message
 news:hbq76m$18in$1 digitalmars.com...

 All your posts are showing up empty here Jerome.

Nope, they are perfectly fine. Try configuring your=20 Thunderbird/Mnenhy or use alternative NNTP client.

They show up as attachments for me.

Looks like Outlook Express is crappy too :) Try Opera

I'm using thunderbird, and things work fine.

That's lucky since I'm using Thunderbird too ;) And yes, OE is a=20 piece of crap that doesn't respect standards. I sometimes have=20 problems with messages posted by OE users too... Jerome --=20 mailto:jeberger free.fr http://jeberger.free.fr Jabber: jeberger jabber.fr
Oct 23 2009
prev sibling parent "AJ" <aj nospam.net> writes:
Nick Sabalausky wrote:
 "Denis Koroskin" <2korden gmail.com> wrote in message
 news:op.u17vung8o7cclz korden-pc...
 On Thu, 22 Oct 2009 23:42:06 +0400, AJ <aj nospam.net> wrote:

 ""Jérôme M. Berger"" <jeberger free.fr> wrote in message
 news:hbq76m$18in$1 digitalmars.com...

 All your posts are showing up empty here Jerome.

Nope, they are perfectly fine. Try configuring your Thunderbird/Mnenhy or use alternative NNTP client.

They show up as attachments for me.

Ah yes, for me too.
Oct 22 2009
prev sibling parent "AJ" <aj nospam.net> writes:
Sorry Jerome, I can't change my newsreader just for you.

"Jérôme M. Berger" wrote: 
Oct 22 2009
prev sibling next sibling parent reply Yigal Chripun <yigal100 gmail.com> writes:
On 21/10/2009 23:59, AJ wrote:
 Since D has no header files, how does one create "a library" that another
 developer can use without exposing the implementation?

generated and/or manually edited. IMO this is a design mistake carried over from c/c++.
Oct 21 2009
next sibling parent reply BCS <none anon.com> writes:
Hello Yigal,

 On 21/10/2009 23:59, AJ wrote:
 
 Since D has no header files, how does one create "a library" that
 another developer can use without exposing the implementation?
 

auto generated and/or manually edited. IMO this is a design mistake carried over from c/c++.

What would you prefer? Aside from a better library format you need something to give DMD the information. Switching to a better library format has several issues including requiring more tools to make them and view them as well as it doesn't solve the problem of linking with C libs that don't and never will use this new format. Not fatal issues I'll grant, but what we have works NOW.
Oct 21 2009
parent reply Yigal Chripun <yigal100 gmail.com> writes:
On 22/10/2009 00:14, BCS wrote:
 Hello Yigal,

 On 21/10/2009 23:59, AJ wrote:

 Since D has no header files, how does one create "a library" that
 another developer can use without exposing the implementation?

auto generated and/or manually edited. IMO this is a design mistake carried over from c/c++.

What would you prefer? Aside from a better library format you need something to give DMD the information. Switching to a better library format has several issues including requiring more tools to make them and view them as well as it doesn't solve the problem of linking with C libs that don't and never will use this new format. Not fatal issues I'll grant, but what we have works NOW.

As you said, what is needed is a better lib format. we already have DDL NOW which already has most of what you described above. D can also take advantage of the LLVM framework. why do you need to choose between the two options anyway? dmd can support c header files combined with c libs and use a better D lib format for D code. Another option would be to have a simple tool to convert a bunch of c header files and a C lib to a D lib. The C/C++ way of headers + lib has problems which D inherited as part of the same (broken) design.
Oct 21 2009
next sibling parent reply BCS <none anon.com> writes:
Hello Yigal,

 On 22/10/2009 00:14, BCS wrote:
 
 Hello Yigal,
 
 On 21/10/2009 23:59, AJ wrote:
 
 Since D has no header files, how does one create "a library" that
 another developer can use without exposing the implementation?
 

auto generated and/or manually edited. IMO this is a design mistake carried over from c/c++.

Aside from a better library format you need something to give DMD the information. Switching to a better library format has several issues including requiring more tools to make them and view them as well as it doesn't solve the problem of linking with C libs that don't and never will use this new format. Not fatal issues I'll grant, but what we have works NOW.

DDL NOW which already has most of what you described above. D can also take advantage of the LLVM framework.

Does DDL or LLVM work to generate monolithic executable that use all of D's features and do so for both Win32 and *nux? Also, can I use notepad to view either of those file types?
 
 why do you need to choose between the two options anyway? dmd can
 support c header files combined with c libs and use a better D lib
 format for D code. Another option would be to have a simple tool to
 convert a bunch of c header files and a C lib to a D lib.

Option 1 is a no starter (Walter has said NO the that exact option based on it needing in effect a full C frontend to work) Option 2 in interesting but, it runs flat into to "needs more tools" issue.
 The C/C++ way of headers + lib has problems which D inherited as part
 of the same (broken) design.

Oct 21 2009
next sibling parent Walter Bright <newshound1 digitalmars.com> writes:
BCS wrote:
 Option 1 is a no starter (Walter has said NO the that exact option based 
 on it needing in effect a full C frontend to work)

Even then it won't work 100%, as many C headers do things with macros that are unrepresentable in D without some manual intervention.
Oct 21 2009
prev sibling parent reply Yigal Chripun <yigal100 gmail.com> writes:
On 22/10/2009 00:57, BCS wrote:
 Hello Yigal,

 On 22/10/2009 00:14, BCS wrote:

 Hello Yigal,

 On 21/10/2009 23:59, AJ wrote:

 Since D has no header files, how does one create "a library" that
 another developer can use without exposing the implementation?

auto generated and/or manually edited. IMO this is a design mistake carried over from c/c++.

Aside from a better library format you need something to give DMD the information. Switching to a better library format has several issues including requiring more tools to make them and view them as well as it doesn't solve the problem of linking with C libs that don't and never will use this new format. Not fatal issues I'll grant, but what we have works NOW.

DDL NOW which already has most of what you described above. D can also take advantage of the LLVM framework.

Does DDL or LLVM work to generate monolithic executable that use all of D's features and do so for both Win32 and *nux? Also, can I use notepad to view either of those file types?
 why do you need to choose between the two options anyway? dmd can
 support c header files combined with c libs and use a better D lib
 format for D code. Another option would be to have a simple tool to
 convert a bunch of c header files and a C lib to a D lib.

Option 1 is a no starter (Walter has said NO the that exact option based on it needing in effect a full C frontend to work) Option 2 in interesting but, it runs flat into to "needs more tools" issue.
 The C/C++ way of headers + lib has problems which D inherited as part
 of the same (broken) design.


from http://llvm.org/docs/LangRef.html <quote> The LLVM code representation is designed to be used in three different forms: as an in-memory compiler IR, as an on-disk bitcode representation (suitable for fast loading by a Just-In-Time compiler), and as a human readable assembly language representation. This allows LLVM to provide a powerful intermediate representation for efficient compiler transformations and analysis, while providing a natural means to debug and visualize the transformations. The three different forms of LLVM are all equivalent. </quote> IIRC DDL wraps objects/libs with meta-data. while it will be easy to get a text representation with llvm (the equivalence that is mentioned above) why would you want to do it anyway? Automatically extracted documentation to a human format (ddoc, javadoc, etc) is much more useful and more flexible - you can get a printed manual or an interactive and easy to navigate html, you can also get all sorts of graphs and diagrams that would ease understanding of the structure of code. the only valid IMO use case for header files is for linking libs - the compiler can handle just find binary formats for that.
Oct 21 2009
next sibling parent reply Walter Bright <newshound1 digitalmars.com> writes:
Yigal Chripun wrote:
 the only valid IMO use case for header files is for linking libs - the 
 compiler can handle just find binary formats for that.

I was originally going to go with a binary format for that - but it turned out to be pointless. dmd is so fast at parsing, there simply was no advantage to replacing the text file parser with a binary file parser. If you consider the .di file as a "binary format", I think you'll find it fulfills all the purposes of it, as well as being human readable without needing a pretty-printer.
Oct 21 2009
next sibling parent reply Yigal Chripun <yigal100 gmail.com> writes:
On 22/10/2009 02:01, Walter Bright wrote:
 Yigal Chripun wrote:
 the only valid IMO use case for header files is for linking libs - the
 compiler can handle just find binary formats for that.

I was originally going to go with a binary format for that - but it turned out to be pointless. dmd is so fast at parsing, there simply was no advantage to replacing the text file parser with a binary file parser. If you consider the .di file as a "binary format", I think you'll find it fulfills all the purposes of it, as well as being human readable without needing a pretty-printer.

Let me re-phrase myself, since I think you misunderstood: c headers are used for hiding implementation *and* documentation. the latter is accomplished much better by tools such as ddoc, javadoc, etc. This leaves us with the former, which doesn't require the format to be human readable, it doesn't mean you must make it not-readable. the benefits of using the llvm byte-code format are as following: 1) platform neutral 2) has efficient representation for in-memory and an equivalent for on-disk. 3) like with C# and Java, the file *is* the interface, no need to maintain a separate interface file. 4) already implemented with all the required tooling by the LLVM project
Oct 22 2009
next sibling parent reply Walter Bright <newshound1 digitalmars.com> writes:
Yigal Chripun wrote:
 On 22/10/2009 02:01, Walter Bright wrote:
 Yigal Chripun wrote:
 the only valid IMO use case for header files is for linking libs - the
 compiler can handle just find binary formats for that.

I was originally going to go with a binary format for that - but it turned out to be pointless. dmd is so fast at parsing, there simply was no advantage to replacing the text file parser with a binary file parser. If you consider the .di file as a "binary format", I think you'll find it fulfills all the purposes of it, as well as being human readable without needing a pretty-printer.

Let me re-phrase myself, since I think you misunderstood: c headers are used for hiding implementation *and* documentation. the latter is accomplished much better by tools such as ddoc, javadoc, etc. This leaves us with the former, which doesn't require the format to be human readable, it doesn't mean you must make it not-readable. the benefits of using the llvm byte-code format are as following: 1) platform neutral

Check.
 2) has efficient representation for in-memory and an equivalent for 
 on-disk.

Check.
 3) like with C# and Java, the file *is* the interface, no need to 
 maintain a separate interface file.

Check. (D doesn't need bytecode files in addition to .obj files, so LLVM isn't saving on any files compared with D.)
 4) already implemented with all the required tooling by the LLVM project

Check. I'm not really understanding what's wrong with .di files. Further advantages of .di files: 1. Neither .di files nor .obj files are needed for other files to successfully import and reference library code 2. .di files are human readable without any need to learn anything other than D 3. No new file formats to design, document, debug and maintain 4. No extra code needed to implement a .di file reader in the compiler
Oct 22 2009
next sibling parent reply Yigal Chripun <yigal100 gmail.com> writes:
Walter Bright Wrote:

 Yigal Chripun wrote:
 On 22/10/2009 02:01, Walter Bright wrote:
 Yigal Chripun wrote:
 the only valid IMO use case for header files is for linking libs - the
 compiler can handle just find binary formats for that.

I was originally going to go with a binary format for that - but it turned out to be pointless. dmd is so fast at parsing, there simply was no advantage to replacing the text file parser with a binary file parser. If you consider the .di file as a "binary format", I think you'll find it fulfills all the purposes of it, as well as being human readable without needing a pretty-printer.

Let me re-phrase myself, since I think you misunderstood: c headers are used for hiding implementation *and* documentation. the latter is accomplished much better by tools such as ddoc, javadoc, etc. This leaves us with the former, which doesn't require the format to be human readable, it doesn't mean you must make it not-readable. the benefits of using the llvm byte-code format are as following: 1) platform neutral

Check.
 2) has efficient representation for in-memory and an equivalent for 
 on-disk.

Check.
 3) like with C# and Java, the file *is* the interface, no need to 
 maintain a separate interface file.

Check. (D doesn't need bytecode files in addition to .obj files, so LLVM isn't saving on any files compared with D.)
 4) already implemented with all the required tooling by the LLVM project

Check. I'm not really understanding what's wrong with .di files. Further advantages of .di files: 1. Neither .di files nor .obj files are needed for other files to successfully import and reference library code 2. .di files are human readable without any need to learn anything other than D 3. No new file formats to design, document, debug and maintain 4. No extra code needed to implement a .di file reader in the compiler

I think you misunderstood. the idea is *not* to replace .di header files with llvm bit-code files. the idea is to replace d object files lib files with a llvm bit-code equivalents which does not need additional header files. let's go over the list one more time: 1) i can't use obj files from different OSes or even different compilers on the same OS - so definitly *not* platform neutral 2) you need to parse a header file in addition to linking functions from the lib file, how is that better than having one file without needing to do any parsing of headers at all? 3) like Steve said, there is only one file so you don't get syncing problems between the header and the object file. the bit-code object file already contains all the required metadata and doesn't depend on a separate header file. 4)LLVM is already implemented and has all the required tools for its format. ldc for example can take advantage of this easily.
Oct 22 2009
parent reply Walter Bright <newshound1 digitalmars.com> writes:
Yigal Chripun wrote:
 let's go over the list one more time: 1) i can't use obj files from
 different OSes or even different compilers on the same OS - so
 definitly *not* platform neutral

Yes, but the .di files *are* platform neutral.
 2) you need to parse a header file
 in addition to linking functions from the lib file, how is that
 better than having one file without needing to do any parsing of
 headers at all?

You still have to read that file and get it into the D front end's data structures.
 3) like Steve said, there is only one file so you
 don't get syncing problems between the header and the object file.

Setting up a build tool to handle dependencies is trivial, and one already has to do that for object files, but even that step isn't necessary as D can simply use the original source file as its "header" file. .di files aren't necessary at all.
 the bit-code object file already contains all the required metadata
 and doesn't depend on a separate header file.

Something has to convert metadata into the D front end's data structures.
 4)LLVM is already
 implemented and has all the required tools for its format. ldc for
 example can take advantage of this easily.

.di files are already implemented and work across all D implementations! BTW, a point not mentioned is that dmd can build library files directly, without making object files. This would break if there had to be metadata in those object files needed by the front end.
Oct 22 2009
parent reply Yigal Chripun <yigal100 gmail.com> writes:
On 22/10/2009 21:57, Walter Bright wrote:
 Yigal Chripun wrote:
 let's go over the list one more time: 1) i can't use obj files from
 different OSes or even different compilers on the same OS - so
 definitly *not* platform neutral

Yes, but the .di files *are* platform neutral.
 2) you need to parse a header file
 in addition to linking functions from the lib file, how is that
 better than having one file without needing to do any parsing of
 headers at all?

You still have to read that file and get it into the D front end's data structures.
 3) like Steve said, there is only one file so you
 don't get syncing problems between the header and the object file.

Setting up a build tool to handle dependencies is trivial, and one already has to do that for object files, but even that step isn't necessary as D can simply use the original source file as its "header" file. .di files aren't necessary at all.

could just compile everything myself. What we're talking about is commercial companies that do not provide full sources. In Java this is trivial - just provide jar(s), in .Net it's trivial - just provide assemblies. in D you need to provide both a library file *and* di header files.
 the bit-code object file already contains all the required metadata
 and doesn't depend on a separate header file.

Something has to convert metadata into the D front end's data structures.
 4)LLVM is already
 implemented and has all the required tools for its format. ldc for
 example can take advantage of this easily.

.di files are already implemented and work across all D implementations! BTW, a point not mentioned is that dmd can build library files directly, without making object files. This would break if there had to be metadata in those object files needed by the front end.

I was suggesting to convert *both* obj files and lib files to llvm bit-code. such library files will still contain the metadata. what I ultimately want is to have something similar in concept to .net asseblies/java Jars but with native code (no VM involved). LLVM provides the infrastructure to do exactly this: the compiler generates platform neutral D-assemblies (in llvm bitcode) that can be used on any architecture/OS/llvm-compiler. This would also allow us to use libraries written in other languages when there's an appropriate llvm compiler for them (Ruby, scheme, python, etc). Another issue that's not mentioned here is shared libraries and D. there's no one simple way to have D shared libraries, and especially on windows (90% market share...) dlls are *not* a solution at all. there are 3rd party tools like DDL but I'd like to see *one* solution that works on all platforms and directly supported by D. major D libraries need to be shared libs - the runtime, the stdlib, the GUI libs, etc..
Oct 23 2009
next sibling parent reply Walter Bright <newshound1 digitalmars.com> writes:
Yigal Chripun wrote:
 that's a different use case. *If* full sources are available than I 
 could just compile everything myself.
 What we're talking about is commercial companies that do not provide 
 full sources. In Java this is trivial - just provide jar(s), in .Net 
 it's trivial - just provide assemblies. in D you need to provide both a 
 library file *and* di header files.

I just don't see how having another file is any sort of burden. People have been doing it for a very long time.
 I was suggesting to convert *both* obj files and lib files to llvm 
 bit-code. such library files will still contain the metadata.

I understand, but it's a lot of code to write to eliminate a file - and with other downsides like not being human readable.
 what I ultimately want is to have something similar in concept to .net 
 asseblies/java Jars but with native code (no VM involved). LLVM provides 
 the infrastructure to do exactly this: the compiler generates platform 
 neutral D-assemblies (in llvm bitcode) that can be used on any 
 architecture/OS/llvm-compiler. This would also allow us to use libraries 
 written in other languages when there's an appropriate llvm compiler for 
 them (Ruby, scheme, python, etc).

Right now, you can hook D up to any language that supports a C interface. It's not necessary to convince them to use LLVM, too.
 Another issue that's not mentioned here is shared libraries and D.
 there's no one simple way to have D shared libraries, and especially on 
 windows (90% market share...) dlls are *not* a solution at all. there 
 are 3rd party tools like DDL but I'd like to see *one* solution that 
 works on all platforms and directly supported by D. major D libraries 
 need to be shared libs - the runtime, the stdlib, the GUI libs, etc..

Shared libraries are inherently not portable from system to system.
Oct 23 2009
parent reply Yigal Chripun <yigal100 gmail.com> writes:
On 23/10/2009 12:37, Walter Bright wrote:
 Yigal Chripun wrote:
 that's a different use case. *If* full sources are available than I
 could just compile everything myself.
 What we're talking about is commercial companies that do not provide
 full sources. In Java this is trivial - just provide jar(s), in .Net
 it's trivial - just provide assemblies. in D you need to provide both
 a library file *and* di header files.

I just don't see how having another file is any sort of burden. People have been doing it for a very long time.

People have also used horses for transportation for a very long time and yet they got replaced by cars and planes.
 I was suggesting to convert *both* obj files and lib files to llvm
 bit-code. such library files will still contain the metadata.

I understand, but it's a lot of code to write to eliminate a file - and with other downsides like not being human readable.

it's mostly integration glue code but it would be much easier to do in a compiler that already uses LLVM as its backend like LDC. I also agree with other people that said that in the long term they (and I) would like to see the reference implementation (DMD) based on LLVM. There are all those benchmarks by bearophile and others that show weak spots in DMD compared to LLVM. As a D user I'd like to get all the performance benefits from a modern otimizing back-end without the need for you to spend your precious time on reinventing the wheel in the DMD backend. If the reference implementation relies on LLVM we get all the optimizations for free and you'll have more time to concentrate on the D language itself.
 what I ultimately want is to have something similar in concept to .net
 asseblies/java Jars but with native code (no VM involved). LLVM
 provides the infrastructure to do exactly this: the compiler generates
 platform neutral D-assemblies (in llvm bitcode) that can be used on
 any architecture/OS/llvm-compiler. This would also allow us to use
 libraries written in other languages when there's an appropriate llvm
 compiler for them (Ruby, scheme, python, etc).

Right now, you can hook D up to any language that supports a C interface. It's not necessary to convince them to use LLVM, too.

pypy for python, rubinious for ruby, something for scheme, clang for c/c++/objective-c/objective-c++, etc.. the current way requires to write/maintain bindings and what if a specific project doesn't provide a C API? in .NET you can use assemblies generated from any .NET language in your project. For example, you can write a C# application that uses an assembly generated from a F# lib. I guess in a way, I'm suggesting to use LLVM as an open .net like platform with native complation in mind instead of VM and managed code.
 Another issue that's not mentioned here is shared libraries and D.
 there's no one simple way to have D shared libraries, and especially
 on windows (90% market share...) dlls are *not* a solution at all.
 there are 3rd party tools like DDL but I'd like to see *one* solution
 that works on all platforms and directly supported by D. major D
 libraries need to be shared libs - the runtime, the stdlib, the GUI
 libs, etc..

Shared libraries are inherently not portable from system to system.

only if you consider dlls and so. Java jars are portable. so do .net assemblies.
Oct 23 2009
parent reply Walter Bright <newshound1 digitalmars.com> writes:
Yigal Chripun wrote:
 Shared libraries are inherently not portable from system to system.

assemblies.

Jars and .nets are not executable code. Dlls and shared libraries are.
Oct 23 2009
next sibling parent Yigal Chripun <yigal100 gmail.com> writes:
On 23/10/2009 21:52, Steven Schveighoffer wrote:
 On Fri, 23 Oct 2009 15:50:18 -0400, Walter Bright
 <newshound1 digitalmars.com> wrote:

 Yigal Chripun wrote:
 Shared libraries are inherently not portable from system to system.

assemblies.

Jars and .nets are not executable code. Dlls and shared libraries are.

.net assemblies built by visual studio are packaged as dlls. Although I don't know exactly how they are executed, I'm sure it's some sort of bytecode. Just saying... -Steve

from wikipedia: In the Microsoft .NET framework, an assembly is a partially compiled code library for use in deployment, versioning and security. There are two types: process assemblies (EXE) and library assemblies (DLL). A process assembly represents a process which will use classes defined in library assemblies. .NET assemblies contain code in CIL, which is usually generated from .NET languages, and then compiled into machine language at runtime by the CLR just-in-time compiler. An assembly can consist of one or more files. Code files are called modules. An assembly can contain more than one code module and since it is possible to use different languages to create code modules it is technically possible to use several different languages to create an assembly. I read somewhere (I can't seem to find the reference ATM) that if you install a .net app with signed assemblies, the installer will compile the assemblies into native executable code (ahead-of-time) and will store them in a system cache. all the system assemblies are pre-compiled like this.
Oct 23 2009
prev sibling parent Yigal Chripun <yigal100 gmail.com> writes:
On 23/10/2009 21:52, Steven Schveighoffer wrote:
 On Fri, 23 Oct 2009 15:50:18 -0400, Walter Bright
 <newshound1 digitalmars.com> wrote:

 Yigal Chripun wrote:
 Shared libraries are inherently not portable from system to system.

assemblies.

Jars and .nets are not executable code. Dlls and shared libraries are.

.net assemblies built by visual studio are packaged as dlls. Although I don't know exactly how they are executed, I'm sure it's some sort of bytecode. Just saying... -Steve

http://www.programmersheaven.com/2/FAQ-DOTNET-DOTNET-Assembly-Explained
Oct 23 2009
prev sibling parent reply Michel Fortin <michel.fortin michelf.com> writes:
On 2009-10-23 03:52:10 -0400, Yigal Chripun <yigal100 gmail.com> said:

 I was suggesting to convert *both* obj files and lib files to llvm 
 bit-code. such library files will still contain the metadata.
 
 what I ultimately want is to have something similar in concept to .net 
 asseblies/java Jars but with native code (no VM involved). LLVM 
 provides the infrastructure to do exactly this: the compiler generates 
 platform neutral D-assemblies (in llvm bitcode) that can be used on any 
 architecture/OS/llvm-compiler. This would also allow us to use 
 libraries written in other languages when there's an appropriate llvm 
 compiler for them (Ruby, scheme, python, etc).

The LLVM bitcode is too much low-level for that. It won't carry enough information about types for correct type checking in D, and it cannot express templates. True, you can express arbitrary metadata in bitcode, but that'd be a whole new format to create and support... Perhaps the solution is to embed the "header file" (I mean the '.di' file) into the generated object file itself, and make DMD check existing object files for an embedded interface. That could work independently of the object file format too. -- Michel Fortin michel.fortin michelf.com http://michelf.com/
Oct 23 2009
parent Yigal Chripun <yigal100 gmail.com> writes:
On 23/10/2009 14:44, Michel Fortin wrote:
 On 2009-10-23 03:52:10 -0400, Yigal Chripun <yigal100 gmail.com> said:

 I was suggesting to convert *both* obj files and lib files to llvm
 bit-code. such library files will still contain the metadata.

 what I ultimately want is to have something similar in concept to .net
 asseblies/java Jars but with native code (no VM involved). LLVM
 provides the infrastructure to do exactly this: the compiler generates
 platform neutral D-assemblies (in llvm bitcode) that can be used on
 any architecture/OS/llvm-compiler. This would also allow us to use
 libraries written in other languages when there's an appropriate llvm
 compiler for them (Ruby, scheme, python, etc).

The LLVM bitcode is too much low-level for that. It won't carry enough information about types for correct type checking in D, and it cannot express templates. True, you can express arbitrary metadata in bitcode, but that'd be a whole new format to create and support... Perhaps the solution is to embed the "header file" (I mean the '.di' file) into the generated object file itself, and make DMD check existing object files for an embedded interface. That could work independently of the object file format too.

I like this idea if that's possible to do. And this would require less code since .di files are already handled by dmd. It still leaves the object files themselves platform specific - objects generated by two different compilers cannot be used in the same executable. But this is a much bigger problem to tackle.
Oct 23 2009
prev sibling parent reply BCS <none anon.com> writes:
Hello Walter,

 Check. (D doesn't need bytecode files in addition to .obj files, so
 LLVM isn't saving on any files compared with D.)
 

The suggestion is NOT to replace .di file with LLVM bytecode. The Suggestion is to replace .obj files with LLVM bytecode and do away with .di all together. (Not that I like the idea all that much)
Oct 22 2009
parent reply Walter Bright <newshound1 digitalmars.com> writes:
BCS wrote:
 Hello Walter,
 
 Check. (D doesn't need bytecode files in addition to .obj files, so
 LLVM isn't saving on any files compared with D.)

The suggestion is NOT to replace .di file with LLVM bytecode. The Suggestion is to replace .obj files with LLVM bytecode and do away with .di all together. (Not that I like the idea all that much)

That locks the D front end, and hence all D implementations, to LLVM and the LLVM toolchain.
Oct 22 2009
parent Yigal Chripun <yigal100 gmail.com> writes:
On 22/10/2009 21:48, Walter Bright wrote:
 BCS wrote:
 Hello Walter,

 Check. (D doesn't need bytecode files in addition to .obj files, so
 LLVM isn't saving on any files compared with D.)

The suggestion is NOT to replace .di file with LLVM bytecode. The Suggestion is to replace .obj files with LLVM bytecode and do away with .di all together. (Not that I like the idea all that much)

That locks the D front end, and hence all D implementations, to LLVM and the LLVM toolchain.

the specification of the llvm bitcode is freely available and you can write your own tools if you don't want to depend on theirs. Seems redundant to reinvent the wheel though since llvm is open source and everything is freely available.
Oct 23 2009
prev sibling parent "AJ" <aj nospam.net> writes:
"Yigal Chripun" <yigal100 gmail.com> wrote in message 
news:hbp0hh$1i24$1 digitalmars.com...
 the benefits of using the llvm byte-code format are as following:
 1) platform neutral

Ha! I consider it another platform!
 2) has efficient representation for in-memory and an equivalent for 
 on-disk.
 3) like with C# and Java, the file *is* the interface, no need to maintain 
 a separate interface file.
 4) already implemented with all the required tooling by the LLVM project
 

Oct 22 2009
prev sibling parent reply Lionello Lunesu <lio lunesu.remove.com> writes:
On 22-10-2009 8:01, Walter Bright wrote:
 Yigal Chripun wrote:
 the only valid IMO use case for header files is for linking libs - the
 compiler can handle just find binary formats for that.

I was originally going to go with a binary format for that - but it turned out to be pointless. dmd is so fast at parsing, there simply was no advantage to replacing the text file parser with a binary file parser. If you consider the .di file as a "binary format", I think you'll find it fulfills all the purposes of it, as well as being human readable without needing a pretty-printer.

There's no need for a new format: D's name mangling has all information necessary to reconstruct a function's full signature. The only thing missing is the vtable layout: the order of those functions and any public/protected data members. Now, if dmd would include some kind of data in the lib for that, the whole .di could theoretically be reconstructed from the .lib. The problem with .di is not so much the extra file, but the added build complexity: the .di must match the .lib; the compiler must find the .di, the linker must find the .lib; and what .di goes with what .lib? They both can have any name, in fact one lib can need any number of .di's. Also: a .di needs to mention private class members as well, for the class layout to match. This should not be necessary. The argument that 'people have been doing it for a long time' is a bad one. There's a reason you've started D after all, even though people have been doing things a certain way for a long time. Perhaps it's my Pascal background, but I miss how I did not have to worry about include paths and all that then, and I like how I don't have to worry about it when using C# now. L.
Oct 24 2009
next sibling parent "AJ" <aj nospam.net> writes:
"Lionello Lunesu" <lio lunesu.remove.com> wrote in message 
news:hbulk2$1jt8$1 digitalmars.com...
 On 22-10-2009 8:01, Walter Bright wrote:
 Yigal Chripun wrote:
 the only valid IMO use case for header files is for linking libs - the
 compiler can handle just find binary formats for that.

I was originally going to go with a binary format for that - but it turned out to be pointless. dmd is so fast at parsing, there simply was no advantage to replacing the text file parser with a binary file parser. If you consider the .di file as a "binary format", I think you'll find it fulfills all the purposes of it, as well as being human readable without needing a pretty-printer.

There's no need for a new format: D's name mangling has all information necessary to reconstruct a function's full signature.

Seemingly (i.e., "it would seem to be so"), D assumes that that one thing is the only value of a header file.
Oct 25 2009
prev sibling parent Walter Bright <newshound1 digitalmars.com> writes:
Lionello Lunesu wrote:
 There's no need for a new format: D's name mangling has all information 
 necessary to reconstruct a function's full signature.

There's a lot more needed than just function signatures and vtbl layouts. Templates, enums, consts, struct/class fields, interfaces, etc.
 Perhaps it's my Pascal background, but I miss how I did not have to 
 worry about include paths and all that then, and I like how I don't have 
 to worry about it when using C# now.

Somehow, you're going to have to tell the build system which files to use.
Oct 26 2009
prev sibling next sibling parent reply BCS <none anon.com> writes:
Hello Yigal,

 On 22/10/2009 00:57, BCS wrote:
 
 Hello Yigal,
 
 As you said, what is needed is a better lib format. we already have
 DDL NOW which already has most of what you described above. D can
 also take advantage of the LLVM framework.
 

of D's features and do so for both Win32 and *nux? Also, can I use notepad to view either of those file types?

<quote> The LLVM code representation is designed to be used in three different forms: as an in-memory compiler IR, as an on-disk bitcode representation (suitable for fast loading by a Just-In-Time compiler), and as a human readable assembly language representation. This allows LLVM to provide a powerful intermediate representation for efficient compiler transformations and analysis, while providing a natural means to debug and visualize the transformations. The three different forms of LLVM are all equivalent. </quote>

So, if your library has LLVM code representation, then it's easier to get to but just as bad as reading a ASM dump from the compiler. I'm being more than a bit sarcastic there, but keep in mind that 99% of the info I'm interested in isn't in the assembly code (function names, argument names, types, comments) and/or would be better viewed as the original source.
 
 IIRC DDL wraps objects/libs with meta-data.
 
 while it will be easy to get a text representation with llvm (the
 equivalence that is mentioned above) why would you want to do it
 anyway? Automatically extracted documentation to a human format (ddoc,
 javadoc, etc) is much more useful and more flexible - you can get a
 printed manual or an interactive and easy to navigate html, you can
 also get all sorts of graphs and diagrams that would ease
 understanding of the structure of code.

I'm cynical enough that I'd bet if D switches to a "smarter lib format" a lot of people would manage to forget the documentation. With the current system, the library must be shipped with, at a minimum, a human readable list of prototypes.
 
 the only valid IMO use case for header files is for linking libs - the
 compiler can handle just find binary formats for that.
 

Truth be told I don't use .di files at all because I have yet to need to use a codebase where I didn't have full source.
Oct 22 2009
parent reply Yigal Chripun <yigal100 gmail.com> writes:
On 22/10/2009 18:52, BCS wrote:
 Hello Yigal,

 On 22/10/2009 00:57, BCS wrote:

 Hello Yigal,

 As you said, what is needed is a better lib format. we already have
 DDL NOW which already has most of what you described above. D can
 also take advantage of the LLVM framework.

of D's features and do so for both Win32 and *nux? Also, can I use notepad to view either of those file types?

<quote> The LLVM code representation is designed to be used in three different forms: as an in-memory compiler IR, as an on-disk bitcode representation (suitable for fast loading by a Just-In-Time compiler), and as a human readable assembly language representation. This allows LLVM to provide a powerful intermediate representation for efficient compiler transformations and analysis, while providing a natural means to debug and visualize the transformations. The three different forms of LLVM are all equivalent. </quote>

So, if your library has LLVM code representation, then it's easier to get to but just as bad as reading a ASM dump from the compiler. I'm being more than a bit sarcastic there, but keep in mind that 99% of the info I'm interested in isn't in the assembly code (function names, argument names, types, comments) and/or would be better viewed as the original source.

even though it looks like ASM it is not the same. the llvm will contain the info (function names, argument names, types, comments) as metadata. visual studio has a view to see all metadata in an assembly, and D IDEs will implement a similar properties view to show the same info. comparing to original source is useless - commercial companies may want to protect their commercial secrets and provide you with only a binary file and the bare minimum to use that file in your projects. D needs to support that option. of course it would be wonderfull if everything would be open-source but D can't force this on everyone and if we want D to be mainstream it needs to support such paradigms as well.
 IIRC DDL wraps objects/libs with meta-data.

 while it will be easy to get a text representation with llvm (the
 equivalence that is mentioned above) why would you want to do it
 anyway? Automatically extracted documentation to a human format (ddoc,
 javadoc, etc) is much more useful and more flexible - you can get a
 printed manual or an interactive and easy to navigate html, you can
 also get all sorts of graphs and diagrams that would ease
 understanding of the structure of code.

I'm cynical enough that I'd bet if D switches to a "smarter lib format" a lot of people would manage to forget the documentation. With the current system, the library must be shipped with, at a minimum, a human readable list of prototypes.

such libraries. givven that D has DDoc to automate this process I'd say it'll encorage developers to provide proper documentation instead of just saying - go read the headers/source.
 the only valid IMO use case for header files is for linking libs - the
 compiler can handle just find binary formats for that.

Truth be told I don't use .di files at all because I have yet to need to use a codebase where I didn't have full source.

Oct 23 2009
next sibling parent Yigal Chripun <yigal100 gmail.com> writes:
On 24/10/2009 01:56, Simen Kjaeraas wrote:
 Yigal Chripun <yigal100 gmail.com> wrote:

 On 22/10/2009 18:52, BCS wrote:
 I'm cynical enough that I'd bet if D switches to a "smarter lib format"
 a lot of people would manage to forget the documentation.
 With the current system, the library must be shipped with, at a minimum,
 a human readable list of prototypes.

use such libraries. given that D has DDoc to automate this process I'd say it'll encourage developers to provide proper documentation instead of just saying - go read the headers/source.

Wild ideas to make people document code: 1) Make DDoc generation the default, turn off by command line switch. 2) Issue a warning (or even error) when a public function is uncommented. -- Simen

that's too much I think. DDoc should be separated from the compiler and just use the compiler's XML/Json output to generate documentation. Such a separate DDoc program can issue documentation warnings (just like doxygen can).
Oct 23 2009
prev sibling parent reply BCS <none anon.com> writes:
Hello Yigal,

 On 22/10/2009 18:52, BCS wrote:
 
 So, if your library has LLVM code representation, then it's easier to
 get to but just as bad as reading a ASM dump from the compiler.
 I'm being more than a bit sarcastic there, but keep in mind that 99%
 of
 the info I'm interested in isn't in the assembly code (function
 names,
 argument names, types, comments) and/or would be better viewed as the
 original source.

contain the info (function names, argument names, types, comments) as metadata. visual studio has a view to see all metadata in an assembly, and D IDEs will implement a similar properties view to show the same info.

And as soon as you *require* an IDE to view the stuff, working without one goes from 'less than ideal' to functionally impossible. I think we have been over this ground before; I have major issues with tool chains that are more or less impossible to use without a language aware IDE. I know there are productivity gains to be had from IDEs and I know that even in the best of cases working without one will cost something. What I'm saying is that I want it to be *possible* to work without one.
 comparing to original source is useless - commercial companies may
 want to protect their commercial secrets and provide you with only a
 binary file and the bare minimum to use that file in your projects. D
 needs to support that option.

I agree. What I want is that your "binary file and the bare minimum to use that file" includes something with the public API that can be handedly read with a text editor. (Really I'd like DMD to force people it to include a proper well written documentation file with good code examples and a nice tutorial but we all know that's not going to happen).
 I'm cynical enough that I'd bet if D switches to a "smarter lib
 format"
 a lot of people would manage to forget the documentation.
 With the current system, the library must be shipped with, at a
 minimum,
 a human readable list of prototypes.

use such libraries.

If the lib is worth useing, the function names will tell you something.
Oct 27 2009
parent reply Yigal Chripun <yigal100 gmail.com> writes:
On 27/10/2009 22:50, BCS wrote:

 And as soon as you *require* an IDE to view the stuff, working without
 one goes from 'less than ideal' to functionally impossible. I think we
 have been over this ground before; I have major issues with tool chains
 that are more or less impossible to use without a language aware IDE. I
 know there are productivity gains to be had from IDEs and I know that
 even in the best of cases working without one will cost something. What
 I'm saying is that I want it to be *possible* to work without one.

I'm not requiring anything of that sort. I view the metadata as machine readable information that is processed by tools like compilers and third party tools. The metadata is required to link in a binary lib file NOT as documentation of the interface.
 comparing to original source is useless - commercial companies may
 want to protect their commercial secrets and provide you with only a
 binary file and the bare minimum to use that file in your projects. D
 needs to support that option.

I agree. What I want is that your "binary file and the bare minimum to use that file" includes something with the public API that can be handedly read with a text editor. (Really I'd like DMD to force people it to include a proper well written documentation file with good code examples and a nice tutorial but we all know that's not going to happen).

that handily readable something is documentation. NOT header files. If you really insist you can generate man pages or text files but for documentation MUST be easy to navigate such as click-able PDF, HTML, etc. look at this this way: a lib is a binary file with binary meta-data not ment for human beings. in order to know what API functions that lib provides you must provide documentation as described above and that's trivial to generate even without a single comment in the source. if you allow for header files that gives a reason for lazy programmers not to generate the documentation, even though it's as simple as adding a line in the makefile.
 I'm cynical enough that I'd bet if D switches to a "smarter lib
 format"
 a lot of people would manage to forget the documentation.
 With the current system, the library must be shipped with, at a
 minimum,
 a human readable list of prototypes.

use such libraries.

If the lib is worth useing, the function names will tell you something.

read HTML format. not in header files.
Oct 27 2009
parent BCS <none anon.com> writes:
Hello Yigal,

 On 27/10/2009 22:50, BCS wrote:
 
 And as soon as you *require* an IDE to view the stuff, working
 without one goes from 'less than ideal' to functionally impossible. I
 think we have been over this ground before; I have major issues with
 tool chains that are more or less impossible to use without a
 language aware IDE. I know there are productivity gains to be had
 from IDEs and I know that even in the best of cases working without
 one will cost something. What I'm saying is that I want it to be
 *possible* to work without one.
 

machine readable information that is processed by tools like compilers and third party tools. The metadata is required to link in a binary lib file NOT as documentation of the interface.

In theory yes. In practice.... If the meat data can be used for auto compleat then someone will make an IDE tool that does that. Once that happens the meta data can function as documentation and soon some people will start expecting people to use it as documentation. At that point it we functional be documentation. And now, even with the best of intentions, we are where I don't want to be. If it is possible to link a program without some human readable "documentation" you /will/ end up with libraries where the only documentation is non human readable.
 comparing to original source is useless - commercial companies may
 want to protect their commercial secrets and provide you with only a
 binary file and the bare minimum to use that file in your projects.
 D needs to support that option.
 

to use that file" includes something with the public API that can be handedly read with a text editor. (Really I'd like DMD to force people it to include a proper well written documentation file with good code examples and a nice tutorial but we all know that's not going to happen).

you really insist you can generate man pages or text files but for documentation MUST be easy to navigate such as click-able PDF, HTML, etc. look at this this way: a lib is a binary file with binary meta-data not ment for human beings. in order to know what API functions that lib provides you must provide documentation as described above and that's trivial to generate even without a single comment in the source. if you allow for header files that gives a reason for lazy programmers not to generate the documentation, even though it's as simple as adding a line in the makefile

Some fraction of libs will be shipped with the minimum needed to compile and link. If that doesn't include some form of documentation, some fraction of libs will ship without documentation. The point about trivially generateable is exactly the crux of the issue; it trivially generateable *with the right tools*. With the right tools (a good IDE) it's not no only trivial to generate but you don't even need to generate it. And now we are right back where I don;t want to be with a language that end up being nearly impossible to use without a pile of extra tools that are not otherwise needed. .
 I'm cynical enough that I'd bet if D switches to a "smarter lib
 format"
 a lot of people would manage to forget the documentation.
 With the current system, the library must be shipped with, at a
 minimum,
 a human readable list of prototypes.

use such libraries.

something.

read HTML format. not in header files.

"What HTML file? The vendor didn't ship my PHB an HTML file."
Oct 28 2009
prev sibling parent "Simen Kjaeraas" <simen.kjaras gmail.com> writes:
Yigal Chripun <yigal100 gmail.com> wrote:

 On 22/10/2009 18:52, BCS wrote:
 I'm cynical enough that I'd bet if D switches to a "smarter lib format"
 a lot of people would manage to forget the documentation.
 With the current system, the library must be shipped with, at a minimum,
 a human readable list of prototypes.

such libraries. given that D has DDoc to automate this process I'd say it'll encourage developers to provide proper documentation instead of just saying - go read the headers/source.

Wild ideas to make people document code: 1) Make DDoc generation the default, turn off by command line switch. 2) Issue a warning (or even error) when a public function is uncommented. -- Simen
Oct 23 2009
prev sibling next sibling parent reply Walter Bright <newshound1 digitalmars.com> writes:
Yigal Chripun wrote:
 The C/C++ way of headers + lib has problems which D inherited as part of 
 the same (broken) design.

Hardly, as: 1. you don't need to use header files in D at all 2. you can automatically generate .di files, guaranteeing they are not out of sync
Oct 21 2009
next sibling parent "AJ" <aj nospam.net> writes:
"Walter Bright" <newshound1 digitalmars.com> wrote in message 
news:hbo51u$2snd$2 digitalmars.com...
 Yigal Chripun wrote:
 The C/C++ way of headers + lib has problems which D inherited as part of 
 the same (broken) design.

Hardly, as: 1. you don't need to use header files in D at all 2. you can automatically generate .di files, guaranteeing they are not out of sync

The #2 synch issue seems to be the main (only?) reason why such a header generation facility is implemented in D? I find much more value in header files than any benefit (of which I know) of eliminating the synch issue (if it is even an issue at all).
Oct 21 2009
prev sibling parent reply Walter Bright <newshound1 digitalmars.com> writes:
Steven Schveighoffer wrote:
 On Wed, 21 Oct 2009 19:21:32 -0400, Walter Bright 
 <newshound1 digitalmars.com> wrote:
 
 Yigal Chripun wrote:
 The C/C++ way of headers + lib has problems which D inherited as part 
 of the same (broken) design.

Hardly, as: 1. you don't need to use header files in D at all 2. you can automatically generate .di files, guaranteeing they are not out of sync

That second one is not true if you are doing incremental building (ever use a build tool that occasionally screws up and doesn't rebuild something?).

At least it is possible to automate. You cannot automate C/C++ header files, so they are inherently unreliable.
 In addition, the only *true* reason to use .di files is to 
 hide implementation

It's also to speed up compilation.
 -- which the auto generator does *not* do.  So you 
 are back to hand editing and back to sync problems.

If you need to hide implementation, I suggest instead redesigning your interface to use "interface" types, or use the pimpl idiom.
 IMO .di files are as horrible as header files in C and I avoid them like 
 the plague.  I'd hate to have to use them, but so far, I haven't had any 
 public release of proprietary code, so no need for them yet.

I agree they aren't necessary most of the time, I don't agree they are even as close to being as horrible as C headers, unless you are hand-editting them. If you are doing the latter, I suggest something may have gone wrong with the design of your interface.
Oct 22 2009
parent "AJ" <aj nospam.net> writes:
"Walter Bright" <newshound1 digitalmars.com> wrote in message 
news:hbp2a5$1m2a$1 digitalmars.com...
 Steven Schveighoffer wrote:
 On Wed, 21 Oct 2009 19:21:32 -0400, Walter Bright 
 <newshound1 digitalmars.com> wrote:

 Yigal Chripun wrote:
 The C/C++ way of headers + lib has problems which D inherited as part 
 of the same (broken) design.

Hardly, as: 1. you don't need to use header files in D at all 2. you can automatically generate .di files, guaranteeing they are not out of sync

That second one is not true if you are doing incremental building (ever use a build tool that occasionally screws up and doesn't rebuild something?).

At least it is possible to automate. You cannot automate C/C++ header files, so they are inherently unreliable.
 In addition, the only *true* reason to use .di files is to hide 
 implementation

It's also to speed up compilation.
 -- which the auto generator does *not* do.  So you are back to hand 
 editing and back to sync problems.

If you need to hide implementation, I suggest instead redesigning your interface to use "interface" types, or use the pimpl idiom.

And jettison "close to the metal" in one fell swoop?
 IMO .di files are as horrible as header files in C and I avoid them like 
 the plague.  I'd hate to have to use them, but so far, I haven't had any 
 public release of proprietary code, so no need for them yet.

I agree they aren't necessary most of the time, I don't agree they are even as close to being as horrible as C headers, unless you are hand-editting them. If you are doing the latter, I suggest something may have gone wrong with the design of your interface.

That's a very, very paradigmical view/statement.
Oct 22 2009
prev sibling next sibling parent reply Tomas Lindquist Olsen <tomas.l.olsen gmail.com> writes:
On Thu, Oct 22, 2009 at 11:50 AM, Yigal Chripun <yigal100 gmail.com> wrote:
 I think you misunderstood. the idea is *not* to replace .di header files =

 the idea is to replace d object files lib files with a llvm bit-code equi=

 let's go over the list one more time:
 1) i can't use obj files from different OSes or even different compilers =

 2) you need to parse a header file in addition to linking functions from =

any parsing of headers at all?
 3) like Steve said, there is only one file so you don't get syncing probl=

y contains all the required metadata and doesn't depend on a separate heade= r file.
 4)LLVM is already implemented and has all the required tools for its form=


This locks D to the LLVM backend, things like that is never a good idea. Also, LLVM bitcode files produced both by LDC and Clang/llvm-gcc are platform specific. Sure you can process them on any platform, but the source code they were compiled from was platform specific, and so is the resulting bitcode. Using LLVM bitcode as a replacement format for native OMF/COFF/ELF objects, does not give us platform neutrality. -Tomas
Oct 22 2009
parent reply Yigal Chripun <yigal100 gmail.com> writes:
Tomas Lindquist Olsen Wrote:
 
 This locks D to the LLVM backend, things like that is never a good idea.
 

you could say the same thing about .net and Java - Java locks you to .class files and .net locks you to assemblies. there are many JVMs from different vendors for different platforms which are interoperable because of this. IIRC Mono can work with MS assemblies and also there's the interoperability between different .net languages.
 Also, LLVM bitcode files produced both by LDC and Clang/llvm-gcc are
 platform specific. Sure you can process them on any platform, but the
 source code they were compiled from was platform specific, and so is
 the resulting bitcode. Using LLVM bitcode as a replacement format for
 native OMF/COFF/ELF objects, does not give us platform neutrality.
 

I don't know llvm that well but it seems that for clang/llvm-gcc the reason for this is because of the source language (c/c++) which is platform specific. Can you elaborate about this for LDC? where are the problematic parts and what can be done to make the output platform-neutral? I read that platform specific things like sizeof where hardcoded in the resulting bit-code but now they replaced it with a sizeof intrinsic so that the resulting bit-code would not depend on this. are there any other problematic cases like this still remaining?
 -Tomas

Oct 22 2009
parent Yigal Chripun <yigal100 gmail.com> writes:
On 22/10/2009 18:06, Denis Koroskin wrote:
 On Thu, 22 Oct 2009 19:59:04 +0400, Yigal Chripun <yigal100 gmail.com>
 wrote:

 Tomas Lindquist Olsen Wrote:
 This locks D to the LLVM backend, things like that is never a good idea.

you could say the same thing about .net and Java - Java locks you to .class files and .net locks you to assemblies. there are many JVMs from different vendors for different platforms which are interoperable because of this. IIRC Mono can work with MS assemblies and also there's the interoperability between different .net languages.
 Also, LLVM bitcode files produced both by LDC and Clang/llvm-gcc are
 platform specific. Sure you can process them on any platform, but the
 source code they were compiled from was platform specific, and so is
 the resulting bitcode. Using LLVM bitcode as a replacement format for
 native OMF/COFF/ELF objects, does not give us platform neutrality.

I don't know llvm that well but it seems that for clang/llvm-gcc the reason for this is because of the source language (c/c++) which is platform specific. Can you elaborate about this for LDC? where are the problematic parts and what can be done to make the output platform-neutral? I read that platform specific things like sizeof where hardcoded in the resulting bit-code but now they replaced it with a sizeof intrinsic so that the resulting bit-code would not depend on this. are there any other problematic cases like this still remaining?
 -Tomas


D source code: void main() { version (Windows) { writefln("Windows"); } else { writefln("not Windows"); } } Using the same LLVM IR for both platforms would be a mistake in the case above. The only solution would be to carry version and such stuff in IR, too, and resolve at later stages, but this is also problematic.

I think that postponing conditional compilation to a later stage is a reasonable solution.
Oct 23 2009
prev sibling next sibling parent "Denis Koroskin" <2korden gmail.com> writes:
On Thu, 22 Oct 2009 19:59:04 +0400, Yigal Chripun <yigal100 gmail.com>  
wrote:

 Tomas Lindquist Olsen Wrote:
 This locks D to the LLVM backend, things like that is never a good idea.

you could say the same thing about .net and Java - Java locks you to .class files and .net locks you to assemblies. there are many JVMs from different vendors for different platforms which are interoperable because of this. IIRC Mono can work with MS assemblies and also there's the interoperability between different .net languages.
 Also, LLVM bitcode files produced both by LDC and Clang/llvm-gcc are
 platform specific. Sure you can process them on any platform, but the
 source code they were compiled from was platform specific, and so is
 the resulting bitcode. Using LLVM bitcode as a replacement format for
 native OMF/COFF/ELF objects, does not give us platform neutrality.

I don't know llvm that well but it seems that for clang/llvm-gcc the reason for this is because of the source language (c/c++) which is platform specific. Can you elaborate about this for LDC? where are the problematic parts and what can be done to make the output platform-neutral? I read that platform specific things like sizeof where hardcoded in the resulting bit-code but now they replaced it with a sizeof intrinsic so that the resulting bit-code would not depend on this. are there any other problematic cases like this still remaining?
 -Tomas


D source code: void main() { version (Windows) { writefln("Windows"); } else { writefln("not Windows"); } } Using the same LLVM IR for both platforms would be a mistake in the case above. The only solution would be to carry version and such stuff in IR, too, and resolve at later stages, but this is also problematic.
Oct 22 2009
prev sibling parent "Steven Schveighoffer" <schveiguy yahoo.com> writes:
On Fri, 23 Oct 2009 15:50:18 -0400, Walter Bright  
<newshound1 digitalmars.com> wrote:

 Yigal Chripun wrote:
 Shared libraries are inherently not portable from system to system.

assemblies.

Jars and .nets are not executable code. Dlls and shared libraries are.

.net assemblies built by visual studio are packaged as dlls. Although I don't know exactly how they are executed, I'm sure it's some sort of bytecode. Just saying... -Steve
Oct 23 2009
prev sibling parent "Steven Schveighoffer" <schveiguy yahoo.com> writes:
On Wed, 21 Oct 2009 19:21:32 -0400, Walter Bright  
<newshound1 digitalmars.com> wrote:

 Yigal Chripun wrote:
 The C/C++ way of headers + lib has problems which D inherited as part  
 of the same (broken) design.

Hardly, as: 1. you don't need to use header files in D at all 2. you can automatically generate .di files, guaranteeing they are not out of sync

That second one is not true if you are doing incremental building (ever use a build tool that occasionally screws up and doesn't rebuild something?). In addition, the only *true* reason to use .di files is to hide implementation -- which the auto generator does *not* do. So you are back to hand editing and back to sync problems. IMO .di files are as horrible as header files in C and I avoid them like the plague. I'd hate to have to use them, but so far, I haven't had any public release of proprietary code, so no need for them yet. -Steve
Oct 21 2009
prev sibling next sibling parent digited <digited yandex.ru> writes:
AJ Wrote:

 Since D has no header files, how does one create "a library" that another 
 developer can use without exposing the implementation? 
 
 

If you need interfaces, just do them. your_interfaces.d: interface WhatYouWantToShow {} your_code.d: class WhatYouDontWantToShow : somePublicInterface {}
Oct 21 2009
prev sibling next sibling parent "Steven Schveighoffer" <schveiguy yahoo.com> writes:
On Wed, 21 Oct 2009 18:16:48 -0400, AJ <aj nospam.net> wrote:

 "Steven Schveighoffer" <schveiguy yahoo.com> wrote in message
 news:op.u157hfkveav7ka localhost.localdomain...
 On Wed, 21 Oct 2009 17:59:52 -0400, AJ <aj nospam.net> wrote:

 Since D has no header files, how does one create "a library" that  
 another
 developer can use without exposing the implementation?

try dmd -H. .di files are D header files, basically used for the reason you specify.

OK, so header files can be generated. The thing is though, when I am designing at the code level, I start with the declarations (such as class data members and methods) and do the implementation (or one can hand it off to someone else) afterwards. That serves as the "blue print" for further development and remains as first level of documentation as well. Working with just "implementation files" seems to be putting the cart before the horse. While eliminating something unnecessary is something to strive for, I don't think header files are unnecessary in the development process (i.e., I don't think that relegating them to just the situation given with my OP is good, exactly for the reasons of usefullness I gave).

Separating interface from implementation is good -- but not if you have to repeat the interface (as you do with C++ or C). 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. -Steve
Oct 21 2009
prev sibling next sibling parent "Steven Schveighoffer" <schveiguy yahoo.com> writes:
On Wed, 21 Oct 2009 19:31:02 -0400, AJ <aj nospam.net> wrote:

 "Steven Schveighoffer" <schveiguy yahoo.com> wrote in message
 news:op.u15929x0eav7ka 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. 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. Header files with comments are trivially transformed into auto-generated docs (one-liner). -Steve
Oct 21 2009
prev sibling next sibling parent "Steven Schveighoffer" <schveiguy yahoo.com> writes:
On Wed, 21 Oct 2009 23:10:38 -0400, AJ <aj nospam.net> wrote:

 "Steven Schveighoffer" <schveiguy yahoo.com> wrote in message
 news:op.u16j03t2eav7ka localhost.localdomain...
 On Wed, 21 Oct 2009 19:31:02 -0400, AJ <aj nospam.net> wrote:

 "Steven Schveighoffer" <schveiguy yahoo.com> wrote in message
 news:op.u15929x0eav7ka 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
Oct 21 2009
prev sibling next sibling parent "Denis Koroskin" <2korden gmail.com> writes:
On Thu, 22 Oct 2009 23:42:06 +0400, AJ <aj nospam.net> wrote:

 ""J=C3=A9r=C3=B4me M. Berger"" <jeberger free.fr> wrote in message
 news:hbq76m$18in$1 digitalmars.com...

 All your posts are showing up empty here Jerome.

Nope, they are perfectly fine. Try configuring your Thunderbird/Mnenhy o= r = use alternative NNTP client.
Oct 22 2009
prev sibling parent "Denis Koroskin" <2korden gmail.com> writes:
On Fri, 23 Oct 2009 05:20:04 +0400, Nick Sabalausky <a a.a> wrote:

 "Denis Koroskin" <2korden gmail.com> wrote in message
 news:op.u17vung8o7cclz korden-pc...
 On Thu, 22 Oct 2009 23:42:06 +0400, AJ <aj nospam.net> wrote:

 ""J=C3=A9r=C3=B4me M. Berger"" <jeberger free.fr> wrote in message
 news:hbq76m$18in$1 digitalmars.com...

 All your posts are showing up empty here Jerome.

Nope, they are perfectly fine. Try configuring your Thunderbird/Mnenh=


 or
 use alternative NNTP client.

They show up as attachments for me.

Looks like Outlook Express is crappy too :) Try Opera
Oct 22 2009