How to organize sources of complex program?

Question

We're creating very complex embedded system and «sources» contains few projects of Visual C++, IAR, Code Composer Studio and Altium Designer schemes and pcbs. All of that possibly could be in few versions. So, what practice could you advice me to arrange all that stuff? Thank you

Answer 1

Everything that you consider as sources should be under a Source Control System, like SVN. This is the best way to handle versions, revisions, branches and tags. SVN can handle binary files, so you won't have problems with non-text files.

Answer 2

If your C++ source files are numerous and span multiple directories then the effort put into grokking Large Scale C++ Software Design by John Lakos may be very worth it. The main theme of the book is how your physical layout of the software, that is, the arrangement of source code files in directories, limit or extend your ability to modify the software.

Answer 3

Reduce the complexity!

My first engineering professor had a famous first lecture. It consisted of a single equation written on the blackboard:

Perfection = Simplicity

The problem with Source Control Systems is that they manage complexity but also promote it.

Answer 4

I like to have a directory structure that at the top level reflects each of the programmable parts.(i.e. microcontroller, DSP1, FPGA1, FPGA2,...)

I also like to have a subdirectory(ies) that has all the generated files, so it is easy to make a clean source tree. Also make it easy to do a clean build straight from the source code configuration tool. (i.e. get and build from source to binary image(s) in as few steps as possible)

Also have each programmable part have it's own version number, and one version number that reflects each of the combination of the sub component version numbers.

Answer 5

Definitely use source control, if the program itself doesn't support it, just keep the parent folder you use under source control. SVN is my current fav.

As far as how to arrange your files, I noticed you had Altium Designer on your list, that program will a) play nice with source control, and b) arrange your files in an orderly manner, assuming you use their whole 'project' file structure. Look into using their 'PCB' (if that's what your doing) or 'embedded' projects, when you create one, it creates buckets for you to store all your different types of files into.

Even if you don't want to actually use Altium for your files, create a project and look at their directory structure to get an idea about all the files you'll need to keep track of.

Answer 6

I have the same setup as you.

I use Altium Designer for the hardware schematics and PCB design. But I also have Firmware source files and related utilities. And I have mechanical design files.

Here's how I do it:

Project Name
    Firmware
        MainCpu
            trunk
            tags
            branches
        IoCpu
            trunk
            tags
            branches
    Hardware
        MainPcb
            trunk
            tags
            branches
        IoPcb
            trunk
            tags
            branches
        PowerPcb
            trunk
            tags
            branches
    Mechanical
        Chassis
            trunk
            tags
            branches
        Other
            trunk
            tags
            branches

This way all the project files are stored together in the SVN repository. The only down side I've found is that you can't just check out the Project and get the latest FW/HW/MEK files. You have to check out each Head of FW/HW/MEK.

The reason for the separate sub-modules for FW/HW/MEK is that they will get separate version tags.

Answer 7

(Aside from trivial helper classes) put one class in each cpp/h file, and name the cpp/h files the same as the class.

Group related classes files into folders (you can optionally use a hierarchy of namespaces that match the folder structure. The .net approach here is to use a CompanyName.ProductName namespace, with your files stored in a ProductName project/subfolder of your solution). So for example, you might group your Math, I/O, and Drawing classes into separate "subsystem" folders.

Ideally, make these separate sections into re-usable libraries (MyCompany.Math). You'll be glad of this later when you want to develop a new product that will share some of the code. In that case, the top level "folders" become separate projects in their own right, and you can start to work on minimising dependences between them to realise and then enforce a much better overall framework design in your code base.

The ideal within folders is to find a good balance between clutter and sparseness - try to balance the folders so that they have between 5-15 files in each. If fewer, consider merging the folders; if greater, consider adding sub-category folders to break down the complexity.

As long as your classes/files and namespaces/folders have good descriptive names, and your folders are logically structured, you can make an extremely large project very easy to navigate.

At the risk of starting a religious war, I prefer to put the headers and their source files in the same folder so that when you are editing a .cpp the .h is easily accessible rather than having to move up and fown by a folder all the time.