There are a few decisions that you might want to make at the beginning of your project so that you have them answered before you get too deep in to things. We'll go over choosing a license, establishing a directory structure, choosing a revision control system, and a few other things.

Software License

If you choose to place your code online where other people can see it then you'll want to choose a license to release your project under. Choosing a license ensures that you have appropriate protection both in how people use your code and what you can be blamed for. I fantastic resource for seeing what types of licenses are out there and what they mean is choosealicense.com. Jeff Atwood wrote a pretty good article on this as well; it's worth a read. Once you've chosen your license, generally you'll need to include a copy of it at the base of your directory structure and possibly at the top of each file.

For welibc I'm choosing the BSD 3-Clause License for its simplicity, the requirement of attribution, and preventing the ability to be held liable.

Directory Structure

Establishing your directory structure at the beginning will help guide your development and keep the layout clean and organized. The idea is to separate distinct pieces and parts of your project in to their own directories in a way that makes sense to you and your team. As your project grows and changes you may find that your directory structure is really working out or that it seems to complicate things. Don't be afraid to alter it as you go, but don't compromise the structure for one feature if it complicates a lot of other pieces.

I don't expect welibc to be terribly big, but at this point I see three distinct groups of files: source code, public headers, and test code. Both the source and test code will need access to the headers, so I think it's logical to group them in a separate folder. Here is a sample layout of what I have in mind:

welibc/
    ├── license.md
    ├── readme.md
    ├── include
    │   ├── assert.h
    │   ├── limits.h
    │   ├── stdio.h
    │   └── stdlib.h
    ├── src
    │   ├── assert.c
    │   ├── stdio.c
    │   └── stdlib.c
    └── test
        ├── assert_test.c
        ├── main.c
        ├── stdio_test.c
        └── stdlib_test.c

Revision Control System

A revision control system (RCS) assists in managing your code as you add features, remove bugs, and implement new functionality. It is an absolutely essential piece of your project. Without an RCS it is likely that you will lose working code, leave commented out code laying around, and make the same mistakes over again.

An RCS provides two incredibly important features: snapshotting your code and attaching messages to your code. If you're unfamiliar, an RCS works similarly to a library in that you check out your code, edit it, then check it back in (or "commit" it) with the changes along with a message of what you did. This also means that it is entirely up to you and your team to make the best use of these features. You could use an RCS but only have one commit with your finalized piece of software; that's not useful. You could put song lyrics in every commit message you make; that's not useful. These features exist for a reason and you should use them. Seth Robertson wrote a great post that discusses this in more depth.

Alright, I'm glad you chose to use a revision control system but which one should you use? There are a few out there, but there are really about four in major use today:

I don't know that any of them are necessarily better than others, but right now there are two pretty large providers of free source code hosting that both use git: bitbucket and github. They make it easy to share your code as well as browse it through their web interfaces. It's also nice that they are in charge of managing the infrastructure and server side of things; all you have to worry about is writing your code.

For this project I've chosen to host the code at bitbucket using git. I'm not as proficient with git as I would like to be so this will help me become more familiar with it.

Coding Style

The style of your code is something that is often overlooked but is something that can really enhance your project. If all of your code is written the same way with braces in the same spots, the same variable name scheme, and spacing consistency then it's much easier to read the code and spot errors when things get out of place.

What looks better, this?

int greatestcommonDivisor(int a  , int b){
    int c;

    while(a!=0)
{
c = a; a = b % a;
b = c;
}

    return b;}

Or this?

int
greatestCommonDivisor(int a, int b)
{
    int c;

    while (0 != a)
    {
        c = a;
        a = b % a;
        b = c;
    }

    return b;
}

That's an extreme example, but just keep in mind that it'll probably be you coming back later on to fix a bug. Do you really want to make things harder on yourself later?

The style you choose is entirely up to you but I recommend always using the same style throughout all of your code; don't change it between files or folders. There are a few example style guides you could adopt as well:

To get a better idea of what all a style guide encompasses, read the Linux kernel coding style page. It's a pretty fast read and Linus even includes some justifications for why certain styles were chosen.

For welibc I have my own style that I've developed over the past few years which I'll be using. It's not exactly documented somewhere, but maybe I'll do that as part of this project. I'm pretty particular about how my code looks.

Build Automation Software

Unless you're working with just a handful of files then you'll want to pick a build system to handle everything for you. A build system allows you to issue a simple command like "make" or to just click a button and have your entire project built according to the specific settings that you need. A few examples of build systems would be:

Since I'll be doing this work on Linux and I'm already pretty familiar with it, I'll be using GNU make for this project.

Documentation

Documentation is usually the last thing done and is sometimes left out of a project entirely. Including documentation may seem worthless but it can really pay off when you have to find an obscure bug, when you bring in a new developer, or when an experienced developer leaves the team. If you have appropriate documentation then these things go more smoothly.

You should first start with commenting your code appropriately. This can include file and function comments along with documenting particularly tricky pieces of code when you can't figure out how to simplify it any other way. Once you have a consistent method of documenting things then you could look at documentation generators. These are separate programs that parse your source code and generate documentation which generally looks better and is easier to read than your source code. A few documentation generators to consider are:

My plan is to use Doxygen since that's really the only one I've used before. If it isn't customizeable enough to fit into the style of the rest of the website then I might switch to something else.

Conclusion

This may seem like a lot to decide on and setup before you actually get down to writing any code but a little planning can go a long way in keeping your project organized and easy to understand. Having some of these things in place can really make the difference between looking like a hobby and looking like a professionally produced piece of software.

Project Design Decisions