www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Phobos classes member declaration order

reply Alexander <aldem+dmars nk7.net> writes:
Is there any particular reason to declare class members in the middle of the
class, *after* they are referenced many times? core.thread is an example.

This makes some difficulties to find where they are defined. Compiler doesn't
care, but humans do :)

It would be so easy to search for "class X" and see all declarations instead of
scrolling through pages of code looking for declarations, when search doesn't
really helps - it find a lot of references first.

Or at least, if declaration would be before references, that would help a lot.

/Alexander
May 13 2011
next sibling parent reply "Jonathan M Davis" <jmdavisProg gmx.com> writes:
 Is there any particular reason to declare class members in the middle of
 the class, *after* they are referenced many times? core.thread is an
 example.
 
 This makes some difficulties to find where they are defined. Compiler
 doesn't care, but humans do :)
 
 It would be so easy to search for "class X" and see all declarations
 instead of scrolling through pages of code looking for declarations, when
 search doesn't really helps - it find a lot of references first.
 
 Or at least, if declaration would be before references, that would help a
 lot.
I believe that the two most common practices when declaring member variables is either to put them all at the top of the class declaration or all at the bottom. If they're private (as is usually the case), I much prefer to put them at the bottom. In the case of core.thread, it looks like they were grouped based on what they're used for. Most of them still ended up towards the bottom in the private section, but there are two which are in the middle. They are, however, _public_ variables (and const __gshared to boot), so they're constants rather than being normal member variables. As such, it makes some sense to put them up with the public functions, and they're right next to the ones that they go with logically (the priority-related stuff). I'm not sure that that's how I would have laid it out, but I can see why it is the way that it is. I don't think that that is commonly done in the various classes in Phobos however. Of course, technically-speaking, core.thread is in druntime rather than Phobos, though I wouldn't think that that would have much to do with the class' layout other than the fact that it has far more version blocks than would be typical in a Phobos class (since it has to worry about OS-specific stuff far more than is typical with the functionality that Phobos covers). - Jonathan M Davis
May 13 2011
parent reply Alexander <aldem+dmars nk7.net> writes:
On 13.05.2011 23:07, Jonathan M Davis wrote:

 I believe that the two most common practices when declaring member variables 
 is either to put them all at the top of the class declaration or all at the 
 bottom. If they're private (as is usually the case), I much prefer to put them 
 at the bottom.
Could you please tell me, why you put them at the bottom? I just want to understand why declarations at the bottom are better than at the top... especially when it makes search difficult when working with someone else code... For instance, talking about core.thread, it took me some time to find the type of m_addr (I am digging for some mysterious segfault in Thread.priority), as this member is used quite often, so search, of course, took some time. Given the size of this code, even finding class bottom was a problem. Sure, there are some IDE's or editors which can point you exactly to declaration, but none are available for Linux in text mode, AFAIK... /Alexander
May 13 2011
next sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
Alexander wrote:
 Given the size of this code, even finding class bottom was a
 problem.
If you use vi or emacs I believe, you can use the % command to do brace matching to jump right to the bottom.
 Sure, there are some IDE's or editors which can point you exactly
 to declaration, but none are available for Linux in text mode,
 AFAIK...
There's always vim.
May 13 2011
next sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
I put my private vars at the bottom as well. The reasoning being that
whoever reads the class (well, usually me) usually wants to know about
the public interface and accessible variables first. The private stuff
is for the class implementer to worry about, that's the way I look at
it. As for searchability? I hit CTRL+END and there's all my variables.
Or I could select an opening brace and do a similar action like VIM's
brace matching.
May 13 2011
prev sibling parent reply Alexander <aldem+dmars nk7.net> writes:
On 13.05.2011 23:48, Adam D. Ruppe wrote:

 If you use vi or emacs I believe, you can use the % command to do
 brace matching to jump right to the bottom.
This requires that I've to position close to opening brace first, and this doesn't really help when declarations are in the middle, unfortunately.
 There's always vim.
Does it parse D code, so I can find where specific variable/function is declared? Simple syntax highlighting and bracket matching is not enough. /Alexander
May 14 2011
parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
I think you can use cscope or ctags for that (there's a plugin that
can let you jump to definitions, not sure if it works for D since I
forgot..). There's information on the wiki4d site. Search for "vim"
and cscope/ctags.
May 14 2011
prev sibling next sibling parent Sean Kelly <sean invisibleduck.org> writes:
On May 13, 2011, at 2:26 PM, Alexander wrote:
=20
  Could you please tell me, why you put them at the bottom? I just want =
to understand why declarations at the bottom are better than at the = top... especially when it makes search difficult when working with = someone else code... I think it's more useful to know what a class does and how it works than = what data it contains. YMMV.
  For instance, talking about core.thread, it took me some time to find =
the type of m_addr (I am digging for some mysterious segfault in = Thread.priority), as this member is used quite often, so search, of = course, took some time. grep can be handy in these situations. A straight search for "m_addr" = turns up 34 lines of results, and the declaration is easy to pick out. = If you want less noise, use a regexp to search for the declaration = itself, knowing that it's going to be: WS type WS "m_addr;". This = search turns up only the declaration line: grep -E '^ *\w+ +m_addr;' thread.d=
May 13 2011
prev sibling next sibling parent "Jonathan M Davis" <jmdavisProg gmx.com> writes:
 On 13.05.2011 23:07, Jonathan M Davis wrote:
 I believe that the two most common practices when declaring member
 variables is either to put them all at the top of the class declaration
 or all at the bottom. If they're private (as is usually the case), I
 much prefer to put them at the bottom.
Could you please tell me, why you put them at the bottom? I just want to understand why declarations at the bottom are better than at the top... especially when it makes search difficult when working with someone else code...
Because they're private. It's quite typical to put all of the private stuff at the bottom. This makes particular sense in C++ where you're dealing with header files, and people are reading the header file to see the public API, not the implementation. As such, you really don't want the private stuff at the top. While we have ddoc documentation to read the API in D rather than header files, I see no reason to change the practice of putting the private stuff at the bottom. And if there is no generated ddoc documentation available, then someone is going to be reading the file to look at the API - much as they would in C++ - and then the private stuff is just in the way. Organizationally, I think that it makes a lot of sense to put the public stuff at the top and the private stuff at the bottom.
 For instance, talking about core.thread, it took me some time to find the
 type of m_addr (I am digging for some mysterious segfault in
 Thread.priority), as this member is used quite often, so search, of
 course, took some time.
 
 Given the size of this code, even finding class bottom was a problem.
 Sure, there are some IDE's or editors which can point you exactly to
 declaration, but none are available for Linux in text mode, AFAIK...
I would expect most IDEs and code editors to be able to at least hop to matching braces. As such, finding the bottom of a class definition is easy. If your editor can't do something even that basic, I'd advise picking a different one. And regardless of that, you can always search for them. If the private member variables were at the top, then it would be something else that you were trying to find (some particular function for instance) and you'd still have to go digging through the class. So, no matter where you put what in a class definition, you're going to have to search for _something_ at some point unless the class is very small. - Jonathan M Davis
May 13 2011
prev sibling parent Bruno Medeiros <brunodomedeiros+spam com.gmail> writes:
On 13/05/2011 22:26, Alexander wrote:
 On 13.05.2011 23:07, Jonathan M Davis wrote:

 I believe that the two most common practices when declaring member variables
 is either to put them all at the top of the class declaration or all at the
 bottom. If they're private (as is usually the case), I much prefer to put them
 at the bottom.
Could you please tell me, why you put them at the bottom? I just want to understand why declarations at the bottom are better than at the top... especially when it makes search difficult when working with someone else code... For instance, talking about core.thread, it took me some time to find the type of m_addr (I am digging for some mysterious segfault in Thread.priority), as this member is used quite often, so search, of course, took some time. Given the size of this code, even finding class bottom was a problem. Sure, there are some IDE's or editors which can point you exactly to declaration, but none are available for Linux in text mode, AFAIK... /Alexander
Why do you want an IDE in text mode?? :s -- Bruno Medeiros - Software Engineer
May 26 2011
prev sibling next sibling parent reply Sean Kelly <sean invisibleduck.org> writes:
On May 13, 2011, at 1:10 PM, Alexander wrote:

 Is there any particular reason to declare class members in the middle =
of the class, *after* they are referenced many times? core.thread is an = example. I generally just declare the interface before implementation. Someone = inspecting the code should care more about what they can call than how = it works.
 This makes some difficulties to find where they are defined. Compiler =
doesn't care, but humans do :) Bottom of the class :-)=
May 13 2011
parent Alexander <aldem+dmars nk7.net> writes:
On 13.05.2011 23:51, Sean Kelly wrote:

 I generally just declare the interface before implementation.  Someone
inspecting the code should care more about what they can call than how it works.
This is true for someone who is not looking for how the code works and how it does things - when hunting bugs, for instance :)
 Bottom of the class :-)
Seems that I've to live with this - at least, when this is not my code :) /Alexander
May 14 2011
prev sibling parent =?ISO-8859-1?Q?Ali_=C7ehreli?= <acehreli yahoo.com> writes:
On 05/13/2011 01:10 PM, Alexander wrote:

 Is there any particular reason to declare class members in the
 middle of the class, *after* they are referenced many times?
Currently I put the member variables at the bottom only because our coding guidelines say so. In personal code, I prefer putting them at the beginning of the class because people who look at the source code are the developers. Member variables tell more about the class than just its public interface. Anybody who cares only about how a class is used is supposed to be looking at its documentation. It is pretty dated at this time, but John Lakos's "Large Scale Software Design" too recommends putting the members at the top. Ali
May 26 2011