Should a class go inside the package which pertains to it?

Question

<?= $vars['title'] ?>

For example, if we were writing a library from scratch, and we had File, FileHandle, DirHandle, and FileSystem classes, would each of these go inside a package/namespace called file? Or one named filesystem? Or os or fs? And if one of the former two, would it be a problem that we had file::File? I know that in Python at least, there are packages structured this way. But it seems a little ugly to have the class name inside the package with the same name.

An alternative would be to put the class at the same level of hierarchy as the package, so you might have:

class File {
    getFileSystem () : FileSystem
    getGroupId () : int
    getSize () : int
    ...
}

// functions which don't need to know the internals of the File class
file::putContents
file::getContents
file::readLine
file::truncate

But then you have the question of... do you put something like FileHandle at the same level as File, or do you put it within the file package? And if the latter, do you use file::FileHandle or simply file::Handle? What about directories? Would you do file::DirHandle? Or should all of this be in an os package?

I guess I'm trying to reconcile the idea of grouping related concepts together into hierarchical packages vs. keeping the names sensible, descriptive, and not redundant.

One potential answer to this that I've considered is that packages should only be used where everything that might go in the package could conceivably have the name of the package in its name. For example, putting a Directory class in the file package wouldn't be right, since you wouldn't say DirectoryFile (or at least, not usually). I contrast, for something like Google Maps, it would make sense to put stuff about Google Maps markers and maps into a package called google::maps::. Likewise, a package named mysql would make sense.

So are packages really only perfect for companies and products, not concepts? Or is it that I'm trying to group concepts at too fine a level? Are there any style guides for this sort of thing?

Answer 1

Packages are tools. If you find yourself sweating the details, just ask yourself what you're really accomplishing when you subdivide or group your classes.

• Some languages e.g. java have special scoping rules and access control for classes residing in the same package. In these cases, don't fight or amend the language's native concept of what a package is for. If you want those access rights between two classes, put them in the same package. If you don't have any reason to suspect that two classes will need these privileges, separate them.
• Some languages give you an ergonomic benefit when some classes tend to be included together if they are in the same package. Again, don't fight the language. Use the tool the way it's intended to be used. If class A must logically be imported every time you import class B, put them in the same package. If they don't, separate them to avoid future clashes.
• If you're in a significant sized codebase and there is no very compelling reason to change, be consistent with the existing organization.
• Otherwise we're talking about aesthetics and human readability. Ask a coworker which package he or she would look in first for your class and that's where it should go. Subdivide to the point that you can scan a package's classes visually, stop subdividing before your coworkers can't immediately guess (correctly) where they are.
• If you're still not sure, get it to the point where if it's wrong, you can fix it quickly, then move on.