# Managing a Project¶

Read time: 42 minutes (10728 words)

I hope you get the idea that we will be writing several C++ code files. Each file will contain code associated with one part of our overall program. For any given project, the number of files you will create depends on the complexity of that project. For now, we need to talk about managing all of that code.

You could (but absolutely do not) just write a bunch of code files and land them in a simple project directory. That is just silly!

Instead, you should think about what each chunk of code is for, who should access that chunk of code, and place it in logical places that make it easy to work with and manage.

There are many ideas on what makes up a good project structure. I am going to show you one that is fine for moderatey big C++ projects. The logic behind each part of this project structure will be explained as we work through the design..

## Project Folder¶

Every project, without exception, should live in a folder named to help you figure out what project this is all about. Most developers come up with a nice catchy name for their project, and that name is slapped on the project folder. We may (and will) have subfolders under this main project folder.

The point is this: every asset associated with this project lives somewhere inside this project folder. That makes it easy to back up the project, or move it from one location in your system to another. This is also essential if we want to use a tool like Git in our work.

You will be placing this top-level folder under the management of Git in this class, and that is something you will discover is done almost for every project you run into these days!

Note

There are other tools available to manage your code, but Git seems to dominate things today!

Exactly where you keep project folders on your system is not really a concern here. However, I recommend collecting all projects for a given organization (or class) in a folder named after that organization (or class). Keep your system “clean”in the sense that you organize things in some logical way, which helps you find things easily. Do not just land everything you do on that “desktop”. That is like working in an office where papers are just thrown everywhere. There is little hope anyone but the poor soul who lives in that office, will be able to find anything!

On all of my systems, I have a folder named cosc2325, for example, and inside of that folder you will find all projects I create for that class. Each project has a distinct name. (unfortunately, sometimes that names is not all that helpful: something like “lab1”.)

Warning

As a developer NEVER name anything with a space in the name. I know Microsoft insists that we do that, but it causes more trouble than we need, so do not do that!

## Project Sub-Folders¶

I am going to recommend a sub-folder layout for your C++ programming projects. This is by no means the only structure you could use, but it makes sense for projects of the sort we will be building. It looks like this:

project_name/
|
+- src/
|
+- lib/
|   |
|   +- component1/
|   |
|   + component2/
|
+- include/
|
+- docs/
|
+- tests/


Every name ending with a slash is a sub-folder name. The diagram is called a “directory tree”.

### Source Code¶

We use that term a lot in programming. The src folder is where I will keep all code associated with the human side of the program. For a C++ program, the main function will live in this folder somewhere. Often that main function will be in a file named main.cpp to make it easy to find.

Other files in this folder will contain code that interacts with the user somehow.

### Library Files¶

All other code files will live under the oibe folder. Since in big projects, we might create smaller chunks of code that logically group some component part of the program, we will allow the use of further sub-folders to keep code associated with a component together. Again, this makes it easy to find code later on as the project grows.

The names you use for these component folders should be related to the purpose of that component, but they are up to you to pick.

### Include Files¶

In C++ programs, we use a “header” file to act as a connector between parts of our program.

The compiler must know enough about every name it encounters as it processes your code to verify that you are using that name properly.

Suppose to write a piece of code in one file that will call a function that lives in another file. When the compiler sees your call to that function, it must know enough about that function to make sure your call is correctly formed. That means we need to know the function name, what it returns, and what parameters it needs. We do not need to know how it does anything, so we do not need to see the code that implements that function.

All of this information can be figured out if we see the first line of that function, which is called the “prototype” of the function. In C++ that is everything up to the curly brace that starts the code for the function. A prototype for a function is a copy of that first line, but we place a semicolon where we would place an open curly bracket and start writing the function code.

We place the prototype for the function in a “header” file with some name. We “include” that header file in any file that will need to call the function. Including a file will cause the prototype lines to be inserted into the code file so the compiler will see it and be happy later when it sees your call.

Note

Since that prototype is a contract between the caoer of the function and the implementer of the function, we also include the headder file with that prototype in the file where the actual implementaton of the fucntion will be found. Here the compiler will check that the actual function code is honoring the contract. If the contract changes both the user and implementer of the function have changes to make in their code.

The problem we face in organizing our code is where to put the include file.

Some developers keep the header files in the same place as the file containing the actual function code. The compiler really does not care as long as you tell it where the header file lives. The problem with this idea is that it puts the implementation code at risk.

Huh!

In a large project, it is important to keep some parts of the code private. That does not mean secret, just out of sight. If two developers get together and come up with the need for a function that does some important task, they have to agree on the “interface” (that prototype line). Once that interface is defined both developers can continue working on their code.

The developer who is going to use the function can go off and write code that calls the new function, even before that function is available. Of course, that code cannot be run until the function implementation really is available, but they can compile their code just fine!

Note

If that developer really needs to be able to run their code before the new function shows up, they can write a dummy implementation that obeys the prototype, but fakes the operation. This version of the function is often called a “mock” of the function.

The fake function just needs to return the right kind of data so the using code will run. These dummy functions are sometimes used in testing, but can be thrown out when the function actually shows up later.

The other developer can go off and create that function. The interface is the contract between them. As long as that interface does not change, life is good.

The user of the function should not need to see the code of the function to use it, and the developer of the function should not need to see the code that uses it. The contract is all both need. If either writes code based this unneeded knowledge, it makes the code “brittle”. Suppose the implementation of the function constructed a data structure, like an array, that was visible outside of that function. The user of the function might know that the array exists and write code that sneaks into that array without the function’s knowledge. If the implementer of the function decides to ditch the array and use a linked list instead, the caller (who should not have done this anyway) will discover their code no longer works!

So sad! Don’t write code like that!

So header files containing this contract line needs to be available to both developers, and we will put those files in a separate folder to reinforce that they are public to all developers.

Note

This idea of keeping some things private is a good one to use in all programming. It goes deeper than just keeping the implementation details hidden away. Object Oriented Programming was invented to give us more control over who has access to almost every name you invent in your code. That helps make sure those names are being used properly, and only by “authorized” users.

### Documentation¶

You absolutely must document your code. We will spend some time on this, so we will not get too deep into thsi idea here. Documentation is not just a bunch of comments in your code, it goes deeper than that!. Real documentation helps the reader, who might even be you some time after you wrote the code, figure out the “why” of that code. The code tells the reader what will happen, but not why! That “why” was locked up in the head of the developer, and we need to record that somewhere! We will put documentation in the docs folder.

### Tests¶

Here is a popular saying:

If you have not tested your code, it does not work!


The only way to prove that saying is wrong, is to test your code - duh!

Testing is not the same as turning on a program ans making sure it “works”. Just because it seemed to work once is no guarantee tat a real user will be happy with it. You need to wring it out and make sure the code cannot be broken by some weird user!

You cannot test a program completely, but you can test it enough to gain confidence in it. The more you test, the more confident you become. (At least until someone finds a way to run your code that you did not test, and you find it is broken anyway!)

Still, we do our best.

Testing is a course in itself. In our work we will test the parts of the program we write. This is called init testing because we are going to test some “unit” of code. We will leave more advanced testing of a complete program for another time. Most of the code we test will be located in the lib folder.

The sad part about testing is that we have to write more code. We need to write a test that runs our code to see if it works. (That raises a question: do we need to test the test code? I think I will skip that idea!)

Our test code will actually be pretty simple. For our C++ projects we will use a neat system that is completely contained in one simple (well not so simple if you try to read it) header file. More on that later.

All test code will be kept in a separate folder named tests.

## Wrapping Up¶

This basic structure is enough to get you started. We will tweak this layout a bit as we work through the class. For now, read up on the mkdir command and see how it can be used to set this project structure up:

mkdir ProjName
cd ProjName
mkdir {src, lib, docs, test}