This is not about comprehension. This is about "I want to find where this class is defined."
I recently had this "insight" where
So something like
Geometry::Math::Vector3
would be in Geometry/Math/Vector3.hpp and Geometry/Math/Vector3.cpp
Have others tried this? (And possible good/bad side effects?)
What other techniques do you use to organize where files reside for largeish C++ projects?
If you use Vim or Emacs, etags / ctags will build indexes for you, to allow jumping between definitions. Microsoft's IDE can do similar things, as long as you don't mind it crashing w/ large variable names. Most (code) editors provide this functionality out of the box.
I pretty much include a module's dependencies in it's separate folder.
And all the times I use the right click option Go to definition to jump.
I find things with grep: grep -n 'class Myclass' *.h *.cpp.
But what you're describing is how Java organizes its files, so it is a reasonable idea.
Having often had to work on large trees organised in a variety of different ways, I tend to rely on searching tools like grep - you'll have it on linux and will be able to get it via msys on windows. This way I can pull out all uses of a particular statement/function easily. I could even re-factor via sed if I was so-minded.
I quite like the Java layout and wouldn't say there's anything wrong with it, aside from sometimes deep folder trees. I personally organise source code into functional sections and it is very much subjective based on how the code breaks up.
Edit - you can also use find to search for file names and do operations on the files with -exec command+opts {} \;
I have a little one line shell script that I placed in my command path, named "fvi", and its contents are as follows:
vi $(find . \( -name "*.cpp" -o -name "*.h" \) -print | xargs grep -l "$@")
Then in the terminal window I just cd to the directory that I want to do a recursive search over, and enter
fvi some_keyword
... and vi is launched with the set of .cpp or .h files containing that keyword, which I can step through quickly with :n and :N. Works pretty well.
The organization approach you suggest seems sound to me. I use it myself and have not found any problems. Source files should not be 10kloc long. :o
I often bend the one file per class rule. When a few small classes are meant to be used together, I'll sometimes just put them all in one module. For example, a custom collection class and its iterators. So long as the file doesn't grow too large.
If you're using namespaces to wrap an enum, or to implement Boost's "detail" idiom, then I wouldn't put them in their own subdirectory.
Most decent IDEs have a symbols browser and a "Find In Files" feature to quickly find classes/functions in a project's source tree.
When I want to familiarize myself with a new C/C++ project, I run the source tree through Doxygen, and enable SOURCE_BROWSER and most EXTRACT_XXX options. Even if there are no Doxygen tags in the source code, you'll still have a nice way to quickly navigate through the source tree. The SOURCE_BROWSER is an awesome feature that produces code listings with hyperlinks to all known entities (namespaces, classes, functions, etc). To search for a class/function, you can go to the index page that Doxygen generates, and use the find feature of your web browser. You can also make Doxygen generate a search engine (which needs PHP).
Doxygen will also produce snazzy "collaboration" diagrams of your classes and header files, so you can see what the dependencies are.
Hope this helps.