Member Discussions

I'm not exactly a professional when it comes to C and C++,
but I do know a bit about design, I like to think...

Is it just me, or is merc.h a completely overkill concept?
It's essentially a file that contains ALL of the
declarations/definitions for everything... every single data
type, every commonly used function, and pages of data that
is only useful in specific files.

I know this probably doesn't matter much as far as the end
product is concerned, but I know splitting it up into
separate files would probably be for the best. It'd require
a little extra work making rules for the makefiles (the
simplicity of not having to worry about anything but
including 1 file when compiling the entire project is
convenient, for sure...), but I think making changes to
specific parts of the code would end up being a lot
smoother.

I recently removed what I thought was kind of rushed
implementation of "colour fields" from my QuickMUD-based
project (which I am messing with right now), and I ended up
having to go through a few files to find all of the things
that referenced it, including some apparently unused things
found in merc.h that I had to dig around for, and I thought
to myself... if this was all just defined in some colour.h
header, it would have been a bit less painful.

Any thoughts on this? Seems like kind of a big undertaking,
but I think I can handle it.

Many muds do use multiple header files. But this is really an organisational thing, it's not going to have any noticable impact on the mud, nor is refactoring legacy code something that many people enjoy doing.

If it bothers you, you might want to look at using a more modern codebase, like tbaMUD.

In the same vein, merc.h is partly organized based on what you were talking about, having a
colour.h kinda thing. There's nothing stopping you from, rather than breaking it into multiple
files, just simply organizing merc.h a bit better, such as having the declarations and such
completely arranged by the files that use them. Then if you need to add/change something, you
open up merc.h and do a search for "colour.c" and you are right where you need to be.

I'm far from a "professional" when it comes to that as well, I would just feel like that not only
would breaking them apart be a bigger headache than it would really be worth, but there are so
many declarations in merc.h that are used in multiple files that you would end up having to
include several headers in so many files, and keeping track of where is where and what you need
where would probably be a headache too.

But of course, whatever you find is easier for you :)

Interface design is hard.

As a programmer who has had to start from the beginning and work my way upward, I know exactly what you're talking about: for a long time, I had one single file containing all declarations that was included everywhere. It was simply easier that way, at least for a small project, because I knew where everything was.

Having everything in one header file is great - you know exactly what file it's in. But as that header file gets huge, finding what you need -inside- the header file becomes your limiting factor. This was the first stage of organizational failure that I ran into.

My advice at this stage is to break up files when it's harder for you to find stuff in the file than it would be to find an isolated file containing it. This way, the most commonly used stuff will get split out first, and you can keep miscellaneous/low use/exotic declarations in merc.h, where they're out of the way and not spamming up your directory trees. In my experience, it's always better to do this kind of refactoring piecemeal than to just slap it in whole-hock.

FYI, Alter Aeon has around 120 header files at around 15kloc total. Two of these contain a big pile of miscellaneous definitions, similar to merc.h, and they clock in at 400 and 1200 loc each. The rest of the headers are pretty isolated and specific.

Don't forget to update your makefile dependencies as you're moving stuff around. If you're not using "makedepend -Y" to automatically update your makefiles, you might want to take a look at the man page.

-dentin

Alter Aeon MUD
http://www.alteraeon.com

This is intended to be a more theoretical discussion of 'when to break up files', from my aged and crusty standpoint. Others may have different views and opinions, but I've found this to be a good description of how I've found my optimized break points and set thresholds for breaking up files.

The basic concept that I believe is most critical to code (and other project) organization boils down to overall search and retrieval time. My ability to find things gates nearly everything I do - how quickly can I find an interface, how quickly can I find a header, how quickly can I find the function that X calls. Because of this, I pretty much optimize my directories, files, and even file internals for manual search time.

When you can find something quickly:

1) you forget less of what you were actually doing
2) you're less likely to get distracted by other stuff
3) if it's quick enough, your tools can act as level 1 or 2 cache for your brain

The problem is that "finding something quickly" is not at all trivial. Let's take directory/file organization as an example:

- If you have too few directories, you'll have so much file spam that you can't find anything without actually looking for it by name.

- If you have too many directories, you'll also have so much directory spam that you can't find anything - but this is worse than having too many files, because now you have to look by name one at a time in the various subtrees.

Let's look at high speed search routines used in the real world for a moment. In rough order of complexity, here's a list of some commonly used lookup structures:

- sparse hash table - O(1)
- sparse radix tables - O(log(N)/log(r))
- binary tree - O(log(N)/log(2))
- list search - O(N)

As is commonly known, the performance difference between these is related to the memory overhead allocated for search - hash tables and radix tables far and away being the fastest, but also consuming the most memory.

This directly relates to your brain when searching for things in your directory structure. You can hold a given number of things in your head for quick access based on the number of neurons you've got and how they're organized. This number of things you can easily manage should, IMHO, be the largest factor in deciding where to set organizational breakpoints.

One common problem I've seen with this is that smart people generally decide organization, and smart people are more rare than less smart people. If you're really smart, but you're working with people who are less smart, it's really easy to set the organizational bar too high for everyone else.

The companies I have worked for professionally have all set the bar higher than I would have preferred - not because it hindered me or other high fliers, but because it hindered our support staff and lowered everyone's net productivity. If you're working with multiple people, this is a critically important thing to keep in mind.

Another downside to setting the organizational bar high is that while you might be able to handle it right now, after five years, you probably can't. That directory and file structure that was so easy to navigate when you were neck deep in it suddenly looks foreign after you've been writing gui libraries for three years.

Keep in mind that search time is the average search time, not the minimum search time. It's ok if some stuff takes forever to find - if you only access it once every four years. The stuff that's used most often should always be at hand. Also remember that what's used often today probably won't be tomorrow.

In short, this is a big, ugly optimization problem with no simple, easy, or obvious answer. Everyone is going to have different breakpoints and different ways in which they run into the limitations of their system. In my opinion, it's worth spending at least a few percent of your overall time, on a continuous basis, examining your current setup; changes in organization often have extremely high leveraging factors.


-dentin

Alter Aeon MUD
http://www.alteraeon.com

Merc? All the code fits snugly in one file. No need for headers.

http://sourcery.dyndns.org/murk.cpp

Sometimes background and preferences drives organization.

My response to merc.h? Kill it with fire.

ctags is a handy utility for navigating source and finding things quickly and it integrates with many popular text editors. It's very helpful if you are working with an unfamiliar project.