First Application

Directory Structure

Series: 1

Introduction


    Throughout this series we’ll walk through how to setup and compile your first C++ program. Hopefully, this should be your initial step in understanding C++ so that you can aim to develop whatever program you desire. However, before we get there, we must first understand the fundamentals, how to organize our code, how to compile it, and then we can begin to explore to our hearts content.

 Directory Structure


    I utilize the same base directory structure for each application I design. Albeit, I sometimes deviate from this initial structure (adding and/or removing directories), the same base directory structure works for most of the applications I design. I encourage you to do the same. Although you may find various directory structures discussed here or there useful, you might want to play around with them a bit, until you’ve tailored one that suites your own personalized needs. Until then, let’s discuss the basics.

    bin

    The first and probably most important directory for each of my applications is the bin directory. The word bin stands for binaries, and there should reside (at least) two directories within this one, which are a debug and release directory. These directories will (each) contain our compiled code. The debug directory will contain code that is intended for debugging, troubleshooting, and general testing of our compiled code. Now, whereas our debug directory is to hold our yet stable testable code, our release directory should contain our stable, sharable, and (yes) releasable code.

    doc

    The second directory that we’ll discuss here is a doc directory. Which, if you’ve guessed it from its name, it should hold any and all documentation (or notes) concerning your application. (This includes configuration files, API documentation, change logs, etc...) Aside from ensuring that you adhere towards clean coding and commenting principles, writing, maintaining, and supplying user documentation, whether it’s intended for user’s, programmer’s, or both, is another important facet of developing software. Not all applications are created equal, and in that vein, not all applications are always as intuitive as we hope. This is why incorporating proper documentation - with your application(s) - will always provide an increased level of insight into your application’s operations.

    include

    Sometimes denoted as inc, the next directory on our list is the include directory. An include directory can hold various things, depending on the nature of your application, language it’s written in, and more. In our case, sense we’ll be writing your initial application in C, we’re going to utilize our include directory for header files. These files will be essentially “included” into our code to bring in class and function declarations, macro definitions, along with any other shared resources that we’d like to store in there. These files are commonly denoted by a *.h, or a *.hpp extension, and become more understood as they’re utilized. For now, just know that header files allow you bring in various function declarations for pre-written code using the #include directive, and we’ll dive deeper into these file types as we advance throughout this series.

    lib

    Next, let’s discuss what a lib directory is. Lib, in our case, is shorthand for library, or libraries. Although, you may write many applications without the need, or use of a third-party library, this is what this directory would be used for. Remember, many applications are built off the backs of pre-written code, libraries, and fundamental concepts that have already been discovered and optimized. There no need in re-inventing the wheel if there’s already an optimal solution that you can simply plugin to your application. Libraries are a great and fundamental asset to have when leveraged correctly, and could hasten the development of your application(s).

    spice

    Albeit, the spice directory isn’t commonly found on many popular directory structure lists, once you understand its use case you should find it as useful as I do. The name spice implies extra, with a hint of instability. In essence, smaller classes and/or functions that are abstract and conceptual in nature should be placed here. Furthermore, any code that feels pre-mature, or as though it should be tested to identify whether it should eventually stay within the overall product, should go here. This is where the term spice comes from. Because the code that resides here isn’t considered a necessary or core part of our application, and it adds extra flavor to it. If the code ends up growing into something more substantial or as a core part of the application than it should migrate into our next directory; the source directory.

    src

    The src (or source) directory should contain your core application files. These are the files, classes, and functions that concretely define your application and its operations. Albeit, you could retain source code within this directory that is in work, or in development, the code should handle “clearly” core aspects or concepts of your application. This is what makes this folder unique from our spice folder. Whereas our spice folder holds code that is more conceptual in nature, our src folder holds code that more absolute in nature.

    test

    The test folder is the final folder that we’ll talk about here. The test folder should contain all of your test code, unit tests, etc… Although, you may not adhere towards the principles of test-driven development for all projects, you should try to adhere towards it whenever possible. Tests ensure that your application operates properly, and continues to do so while behaving as expected. We’ll go over the process of unit tests within a future article. However, for the purposes of this endeavor we won’t be incorporating any this time around.

Conclusion


    Whether you set out to develop a large or small-scale application, it’s important to lay the ground work so that you can easily maintain an overall organized approach towards your application’s development. Ensuring that your code base is, not just organized, however, easy to maintain, can be a guiding mantra for some developers and an unbreakable principle for others. Try early on to set yourself up for success, and generally success follows.

    If you would like to start your application with the above mentioned directory structure, you can gather more information, as well as download a pre-fabricated version of this structure at the following link. Please feel free to comment, contribute, or mention any issues below, or through the support link attached to this Github’s project page.

Please login or register to comment!