473,883 Members | 1,622 Online
Bytes | Software Development & Data Engineering Community
+ Post

Home Posts Topics Members FAQ

C++ Project Organization Guidelines

I think Danny was one cup of coffee shy of full consciousness when he wrote
this, but the gist of it makes sens to me:

"C++ Project Organization Guidelines
Last updated May 26, 2005.
http://www.informit.com/guides/conte...lus&seqNum=175
Last week's article about inline functions subtly brought into the limelight
another important issue, namely how to organize the files of a typical C++
program, or project. This week I discuss this issue and answer the
following questions: How to decide which code components should be included
in a header file and which ones belong to a source file? How many files
should be used in a project have[sic]?"

....

"Poorly-organized projects seldom succeed. Proper organization of project
units, consistent and intelligible file naming conventions and a reliable
configuration management tool (a topic which I didn't discuss here) are
prerequisites for a project's successful completion. Of course, these
measures can't replace talented and experienced developers and meticulous
design. Yet, unlike the latter, project organization is rarely discussed in
programming books."
//----------------------------------------------------------------------
This is the kind of discussion I was hoping to find in Sutter and
Alexanderescu's _Coding Standards_, but didn't. I believe C++ programmers
tend to avoid this kind of discussion because it's too much like politics
and religion. I also believe it's a topic overdue for serious discussion.

I actually don't believe he went nearly far enough. For example, I believe
it is advisable to organize a project into namespaces with file locations
reflecting the namespace hierarchy, and file names reflecting (in general)
class names.

Here's one possible way to arrange a project which I find attractive.
Tue Jul 26 00:23:21:> find . -type d | grep -v /.svn
..
../bin
../doc
../lib
../src
../src/diagram
../src/mtree
../src/osgQt
../src/patControl
../src/rstest
../src/osgqttest
../src/widgets
../build
../build/diagram
../build/mtree
../build/osgQt
../build/patControl
../build/rstest
../build/osgqttest
../build/widgets
../include
../include/math
../include/util
../include/control
../include/diagram
../include/mtree
../include/osgQt
../include/patControl
../include/rstest
../include/osgqttest
../include/widgets

The advantage to splitting src and include into too parallel hierarchies is
that it helps ensure the dependencies are actually separated. Each
namespace has its own build directory which produces its own libraries and
or executables. The executables are placed in ./bin and the libraries are
placed in ./lib. I try to link against the libraries in ./lib rather than
the ones in the build tree because that treats them as they would be
treated in an installed environment.

The listing above has the following namespaces:
control
diagram
math
mtree
osgQt
osgqttest
patControl
rstest
util
widgets

Typically, I create one unit (see Danny's article) per class, and give the
files a name identical to the class name except that the file names have
extensions. The header guards typically (ideally) are of the form
_NAMESPACE_CLAS SNAME_H_. This is one place where the Cpp can hold a subtle
gotcha. Suppose you just use the file name as the foundation for the
header guard, and have two files with the same name in different parts of
the project. Another problem arrises when I rename a class, and thence its
filename. If I forget to rename the header guard, and subsequently create
another class of the same name, I can end up excluding one of the two
before it is processed for the first time.

Sometimes I find myself creating namespace local functions, or a bunch of
tiny classes. When that happens, I try to put them all in one unit with
filenames corresponding to the namespace name.

There are probably many refinements I can still make on my project
organization strategies. For one, I need to strengthen the concept of
interface, and the separation between interface and implementation. This
applies to both classes, and to namespaces.

See for example, the Xerces project:
http://svn.apache.org/viewcvs.cgi/xe...c/xercesc/dom/

Note that they follow very closely the recommendations of Stroustrup
regarding the use of pure interfaces (ABCs). Ironically, this seems to
have originated with the Java implementation of Xerces, and was carried
over when (as I understand things) Xerces was ported to C++. Another point
worth mentioning is the use of #include <xercesc/dom/DOMAttr.hpp>, etc.,
which I would like to tell you reflects the namespace hierarchy (as it
would in my code), but, unfortunately, they use a #define to bracket their
namespaces, and I don't recall what that is defined as, nor where it's
defined.

Another point is that I believe it would be a good idea for C++ programmers
to try to agree on a file name extension convention. I personally
dislike .cpp because it's reminiscent of the C preprocessor, but I can get
over that. .h is problematic because there are subtle differences between
C and C++, and .h can be understood by a multilingual tool to mean a C
header file. I therefore favor .cpp and .hpp. Unfortunately, KDevelop
doesn't currently (correctly) support that option.

I have one critique of Danny's code. I don't believe he needs the
log.close() in the destructor:

// logfile.h
#include <fstream>
#include <string>
class Logfile
{
public: //member functions are declared but not defined:
Logfile(const std::string & path);
~Logfile();
//...
private:
std::ofstream log;
std::string name;
};

// logfile.cpp
#include "logfile.h"
//definitions of functions declared in the .h file
Logfile::Logfil e(const std::string & path) :name(path)
{
log.open(name.c _str());
bool success=log;
//..
}
Logfile::~Logfi le()
{
log.close();
//..
}

Another suggestion some people might make is to use a pointer in the header
file so that there is no memory allocation required if it is simply
#included in another translation unit. In that case he would need a
destructor. I'm not sure of the ramifications of using an auto_ptr in the
class definition. Would that be superior to using a local data member or a
pointer to std::ofstream?
--
If our hypothesis is about anything and not about some one or more
particular things, then our deductions constitute mathematics. Thus
mathematics may be defined as the subject in which we never know what we
are talking about, nor whether what we are saying is true.-Bertrand Russell
Jul 26 '05 #1
1 10932
Another important thing to look into is the header file include
management.

The following article gives some tips about how to manage header
file includes in your project.

http://www.eventhelix.com/RealtimeMa...dePatterns.htm

--
EventStudio 2.5 - http://www.EventHelix.com/EventStudio
Generate Sequence Diagrams in PDF and Word EMF from plain text input

Jul 26 '05 #2

This thread has been closed and replies have been disabled. Please start a new discussion.

Similar topics

6
3625
by: Vagif Abilov | last post by:
We decided to adopt .NET coding guidelines posted by Brad Abrams from Microsoft: http://blogs.msdn.com/brada/archive/2005/01/26/361369.aspx Here is what Brad (and AFAIK Microsoft) suggests regarding project folder structure: "Directory names should follow the namespace for the class For example, I would expect to find the public class "System.Windows.Forms.Control" in "System\Windows\Forms\Control.cs"."
23
2716
by: Steve Jorgensen | last post by:
Hi all, I'm working on a project through a consulting company, and I'm writing some database code for use in another programmer's project in Excel/VBA. The other programmer is working through the same consulting company. I did not initially know this other programmer's experience level, but he seemed down to earth and friendly. I saw some signs of trouble after having him try to integrate some of my code, but chalked it up to him...
3
1889
by: JIM.H. | last post by:
Hello, I used copy project and create a copy of my project with file required at run time to deploy my asp.net application to a DMZ web server. I copied the folder to Web sever and created a web site by pointing this new folder. I have web site name as MySite. How should I launch this in the internet explorer to see if it works. I tried http://MySite it did not bring anything. I have never done this before. Thanks, Jim.
8
1441
by: Dan Konig | last post by:
I have recently aquired vb.net standart edition in order to upgrade and improve a project written by someone else in vb6 for this company I work for. But every time I try to convert it to vb.net I get this message: Upgrade failed: Exception occured: The referenced components CommonDialog SSTab are missing design time licences. How do I fix this problem to continue my work?
0
969
by: thatsMaBoy | last post by:
Hi, I have an ASP.Net web service application. The .Net installer (a deployment project) currently installs the web service in the Default Website area in IIS on the target server PC. This is ok when an organization uses separate IP Addresses for each hosted site, but not ok when the organization expects to host all sites using the same IP Address and use of host headers. The only options available to the user when installing are:
4
1513
by: John | last post by:
I want to write a quick app that will remind me not to slouch at the computer with an Outlook "New Mail Desktop Alert" style pop-up every 15 minutes or so. What I'd like advice on is the best method of timing and displaying the pop-ups that would have the lowest performance impact for other running applications? Best regards
1
1317
by: mysa | last post by:
hello!! i am proposed a project. the project is just like complaining to the ministry or organization about anything through sms... and from there, those organization will receive it and give the feedback to them.. i need to know the sms flow from user to the adminstrator for this project... i'm sorry because i'm less knowledge about this topic thank you!!!
49
3967
by: Martin Unsal | last post by:
I'm using Python for what is becoming a sizeable project and I'm already running into problems organizing code and importing packages. I feel like the Python package system, in particular the isomorphism between filesystem and namespace, doesn't seem very well suited for big projects. However, I might not really understand the Pythonic way. I'm not sure if I have a specific question here, just a general plea for advice. 1) Namespace....
0
2788
by: LoganSquareDon | last post by:
Please distribute this email. Data on both agile and plan-driven projects are welcome. Dear To Whom It May Concern, My name is Donald Buresh, and I am a Ph.D. student at Northcentral University located in Prescott Valley, Arizona. The reason that I am writing to you is because I would like you to participate in an internet survey for my dissertation. The topic of my dissertation is assessing agile project management and customer...
0
9942
marktang
by: marktang | last post by:
ONU (Optical Network Unit) is one of the key components for providing high-speed Internet services. Its primary function is to act as an endpoint device located at the user's premises. However, people are often confused as to whether an ONU can Work As a Router. In this blog post, weíll explore What is ONU, What Is Router, ONU & Routerís main usage, and What is the difference between ONU and Router. Letís take a closer look ! Part I. Meaning of...
0
9792
by: Hystou | last post by:
Most computers default to English, but sometimes we require a different language, especially when relocating. Forgot to request a specific language before your computer shipped? No problem! You can effortlessly switch the default language on Windows 10 without reinstalling. I'll walk you through it. First, let's disable language synchronization. With a Microsoft account, language settings sync across devices. To prevent any complications,...
0
11148
Oralloy
by: Oralloy | last post by:
Hello folks, I am unable to find appropriate documentation on the type promotion of bit-fields when using the generalised comparison operator "<=>". The problem is that using the GNU compilers, it seems that the internal comparison operator "<=>" tries to promote arguments from unsigned to signed. This is as boiled down as I can make it. Here is my compilation command: g++-12 -std=c++20 -Wnarrowing bit_field.cpp Here is the code in...
0
10749
jinu1996
by: jinu1996 | last post by:
In today's digital age, having a compelling online presence is paramount for businesses aiming to thrive in a competitive landscape. At the heart of this digital strategy lies an intricately woven tapestry of website design and digital marketing. It's not merely about having a website; it's about crafting an immersive digital experience that captivates audiences and drives business growth. The Art of Business Website Design Your website is...
0
7133
by: conductexam | last post by:
I have .net C# application in which I am extracting data from word file and save it in database particularly. To store word all data as it is I am converting the whole word file firstly in HTML and then checking html paragraph one by one. At the time of converting from word file to html my equations which are in the word document file was convert into image. Globals.ThisAddIn.Application.ActiveDocument.Select();...
0
5801
by: TSSRALBI | last post by:
Hello I'm a network technician in training and I need your help. I am currently learning how to create and manage the different types of VPNs and I have a question about LAN-to-LAN VPNs. The last exercise I practiced was to create a LAN-to-LAN VPN between two Pfsense firewalls, by using IPSEC protocols. I succeeded, with both firewalls in the same network. But I'm wondering if it's possible to do the same thing, with 2 Pfsense firewalls...
0
5994
by: adsilva | last post by:
A Windows Forms form does not have the event Unload, like VB6. What one acts like?
1
4618
by: 6302768590 | last post by:
Hai team i want code for transfer the data from one system to another through IP address by using C# our system has to for every 5mins then we have to update the data what the data is updated we have to send another system
2
4223
muto222
by: muto222 | last post by:
How can i add a mobile payment intergratation into php mysql website.

By using Bytes.com and it's services, you agree to our Privacy Policy and Terms of Use.

To disable or enable advertisements and analytics tracking please visit the manage ads & tracking page.