www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - Best practices for reading public interfaces

reply "Kenny" <artemalive gmail.com> writes:
I like D modules and it's a major point in the list of major
points why I like D (there is also the second not so nice
wft-list but it's for another post). I'm annoyed with C++
includes and I'm tired to create 2 files every time when I need
to add something new to the project...  But I must admit that one
thing I like in header files is that it is a convenient way to
read public interfaces.

In D we have interface specification and implementation in a
single file and also one approach with unit testing is to put
them immediately after functions which makes writing unit tests
even more easy task (and I like it very much) but again it makes
the gaps between declarations even wider.

So, what are the common approaches for reading public interfaces
in D programs? Especially it would be great to see the answers of
developers who work with more or less big codebases.

The few possible solution I'm thinking about at the moment:

a) Provide D interfaces for corresponding classes (but probably
it's only for more or less complex abstractions and also I won't
use it for Vector3D, also very often I use just regular
functions).

b) Write DDocs and read documentation. The problem here is that
I'm going to use D only for my own projects and in the last time
I tend to write less documentation, for example I do not write it
for the most methods of Vector3D.

c) Do nothing special, just write D modules and try to figure out
public interfaces reading its code. Maybe it works in practice.

Thanks,
Artem.
Feb 21 2015
next sibling parent reply "anonymous" <anonymous example.com> writes:
On Saturday, 21 February 2015 at 20:46:09 UTC, Kenny wrote:
 b) Write DDocs and read documentation. The problem here is that
 I'm going to use D only for my own projects and in the last time
 I tend to write less documentation, for example I do not write 
 it
 for the most methods of Vector3D.
If you're only interested in the signatures, empty documentation comments give you that.
Feb 21 2015
parent reply "Kenny" <artemalive gmail.com> writes:
On Saturday, 21 February 2015 at 20:56:26 UTC, anonymous wrote:
 On Saturday, 21 February 2015 at 20:46:09 UTC, Kenny wrote:
 b) Write DDocs and read documentation. The problem here is that
 I'm going to use D only for my own projects and in the last 
 time
 I tend to write less documentation, for example I do not write 
 it
 for the most methods of Vector3D.
If you're only interested in the signatures, empty documentation comments give you that.
Is is possible to generate signatures without modifying source code?
Feb 22 2015
parent ketmar <ketmar ketmar.no-ip.org> writes:
On Sun, 22 Feb 2015 16:12:49 +0000, Kenny wrote:

 On Saturday, 21 February 2015 at 20:56:26 UTC, anonymous wrote:
 On Saturday, 21 February 2015 at 20:46:09 UTC, Kenny wrote:
 b) Write DDocs and read documentation. The problem here is that I'm
 going to use D only for my own projects and in the last time I tend to
 write less documentation, for example I do not write it for the most
 methods of Vector3D.
If you're only interested in the signatures, empty documentation comments give you that.
=20 Is is possible to generate signatures without modifying source code?
generating .di file will strip out all non-template code. maybe we need a=20 cli switch to strip out templates too -- you could fill ER.=
Feb 22 2015
prev sibling parent reply "MrSmith" <mrsmith33 yandex.ru> writes:
On Saturday, 21 February 2015 at 20:46:09 UTC, Kenny wrote:
 I like D modules and it's a major point in the list of major
 points why I like D (there is also the second not so nice
 wft-list but it's for another post). I'm annoyed with C++
 includes and I'm tired to create 2 files every time when I need
 to add something new to the project...  But I must admit that 
 one
 thing I like in header files is that it is a convenient way to
 read public interfaces.

 In D we have interface specification and implementation in a
 single file and also one approach with unit testing is to put
 them immediately after functions which makes writing unit tests
 even more easy task (and I like it very much) but again it makes
 the gaps between declarations even wider.

 So, what are the common approaches for reading public interfaces
 in D programs? Especially it would be great to see the answers 
 of
 developers who work with more or less big codebases.

 The few possible solution I'm thinking about at the moment:

 a) Provide D interfaces for corresponding classes (but probably
 it's only for more or less complex abstractions and also I won't
 use it for Vector3D, also very often I use just regular
 functions).

 b) Write DDocs and read documentation. The problem here is that
 I'm going to use D only for my own projects and in the last time
 I tend to write less documentation, for example I do not write 
 it
 for the most methods of Vector3D.

 c) Do nothing special, just write D modules and try to figure 
 out
 public interfaces reading its code. Maybe it works in practice.

 Thanks,
 Artem.
You can also fold all the function bodies in your editor, this helps me to read massive sources.
Feb 22 2015
parent "Kenny" <artemalive gmail.com> writes:
On Sunday, 22 February 2015 at 12:13:02 UTC, MrSmith wrote:
 You can also fold all the function bodies in your editor, this 
 helps me to read massive sources.
Oh, I almost forgot about this feature, never used it in C++ but for D it looks promising. Thanks!
Feb 22 2015