Writing Your Code

Here is a file, sitting somewhere on your computer:

You constructed this file somehow, and saved it on your computer someplace (maybe on your “desktop”). You were supposed to do this, because your boss (or teacher) gave you the job of writing it. You did that and you are done! All you need to do it get it to your boss. Once you get that done, you can move on to something else!

So you email it to your boss.

WRONG!

Did you notice something in that file?

  • Will it run? (The project is using C++, by the way!)
  • How do you run it?
  • Did you run it?
  • Where is the documentation
  • What tests have you run on this?

This is not good!

The Right Way!

Warning

This lecture is fairly long, but the concepts it introduces are very important. Take the time to read it and plan on working this way through this course. You will be better prepared for your work in later courses, or jobs!

There are some obvious issues with the above scenario. Let’s tackle them one by one.

Projects

Your job is not to just create a pile of text that claims to be a program, or even a piece of a larger program. It is to build something that works, something that has been tested, and is documented well enough to be useful to someone. That piece of code may have a long life and do important work, or it may disappear from sight, and the time you spent writing it was wasted.

You can help make sure it lives on!

Organizing Projects

Projects are well organized things, with a structure and tool set in place to make sure we create good products. That means we must write our code in a way that fits into this project structure. One file, standing alone is not going to work.

We start off by creating a single project folder somewhere on your development system. That place should be chosen carefully, and it should be managed with some form of backup system. If this job is important to you, you do not want to risk losing your work because of a system crash (Windows updates, anyone?) or because someone stole your laptop!

Those of you addicted to an IDE probably let that tool set things up for you. Sometimes that is fine, but too often the structure set up by default by your IDE does not match the structure your project really needs. (Have you ever really looked at the files created by even a simple IDE to see what they are, and do you even know why they are there?)

Many projects have a simple structure. In my classes, I keep things as simple as I can. Here is the basic setup I recommend to my students:

+- orgname/ - what organization (company) is this work for
    |
    +- projectname/ - this is the name of the project
        |
        +- src/ - human interface components (like ``main.cpp``)
        |
        +- lib/ - class source files for application components
        |
        +- include/ - header files for classes definitions
        |
        +- test/ - where all test code lives
        |
        +- doc/ - where the real project documentation lives

In a big project these folders might be subdivided, but for most of my classes, this works fine.

The point is that we now have a structure that makes sense and we can find things easily.

Managing your Code

These days, creating code that is not being managed by a tool like Git is just asking for trouble. Source Code Control tools let you create program files, and make changes to them without worrying that you might break something and have to manually try to reverse what you just did. I use Git for almost all of my work now, and the open-source work I do is hosted on my GitHub account. GitHub is just a server where millions of open-source projects live. The code there is stored as both a backup, and a place to share ideas with other developers.

Warning

Of course, you would not use the public side of GitHub to host any project you do for your boss, or for your teacher. That is sure to cause problems.

Instead, company or school work should be hosted on private servers. You can do this on GitHub (for a fee) or manage your code on some other server. I have set up a private GitLab server for classes years ago. Currently, I use GitHub Classroom for most of my classes. That system provides a private home for student projects. We will be using that system in this class.

Git tracks the timeline of your development. It is a complex tool if used at the professional level, but it can be used in simple ways when you just get started. For most of my classes. I keep things simple.

Building

Raw code is never enough. We need to know how to build the application (or at least how to test the component if that is what you are building). Your IDE might do this for you, or you might use a build tool. In my classes, I want my students to be familiar with common tools outside of their IDE. I use make, which has been around a long time, and is actually used in some IDE systems! That means I place a single build file, named Makefile in the top level of my project folder.

In this class, we will see how to set up a Makefile that will help manage your project.

Build Tools

Since most of my classes use C++, I use the Gnu C++ compiler to build projects. This package is high-quality, available for all platforms, and meets industry standards. Of course, you can use other tools, but that is up to you. The point is that you should make sure your application can be built properly, using a tool set that will satisfy the requirements of your boss!

Our Makefile will assume that the needed tools are installed so you can run them directly from the command line. If you use an IDE, that may not work, since IDE’s often install the build tools within their framework.

Testing

Of course, your code should be tested. That does not mean that you compiled it and it ran - once. That really means that you have subjected it to a set of tests designed to give everyone confidence that your code is really usable. Testing is a common thing in today’s development world, so you should get used to testing now.

I use a simple C++ testing framework called catch.hpp. This tool is based on a single header file you can include in a test set. Tests are easy to write, so do not neglect them. For learning how to add testing to your work flow, this is a good place to start.

Of course, your boss may have other testing procedures and tools you need to use.

I also automate running my tests on a completely different machine from the one I work on. I use TravisCI, a free service for open-source projects, to build and run my code as soon as I update things on GitHub. This is a very neat way to make sure your project is in good shape as you work. It also gives those other folks looking over you work some confidence that this project might be worth their time to explore.

Documentation

Documentation is not as simple as adding a few comments to your code. If your code is going to have a chance to survive a long time, it is vital that you write down the thinking that went into you code. Projects whose documentation pages say “read the code” have missed the point entirely. Yes, the code says what will happen when it runs, but it fails to say why the code was constructed the way it ended up. Were there issues you faced, and decisions you made that might affect future bug fixes, or modifications needed to add new features? None of that ends up in a simple comment.

Worse yet, comments in code often get ignored when code is modified. My favorite example of that is this line I saw in a real program, years ago:

X = 3;  /* set X to 2 */

My first reaction oto this comment was shock: why would you bother to put that comment in. Then my reaction turned to distrust! I do not trust that code, and I do not really trust the programmer who wrote that line.

I use a Python tool named Sphinx _to write all of my documentation. It allows me to write content in a simple way, without worrying about style issues. It uses a simple markup called reStructuredText, which can be created with any programmer’s text editor. The resulting documents can be formatted for display on a web server, or can be used to generate PDF files if you like.

Note

To build PDF output I use the LaTeX system, which is a big package used by students at many universities (like Texas State) to produce publication quality thesis or dissertation works. It is also used by many publishers and journals, so it is worth learning about,

Some documentation tools realy do nothing but help you explore your code. That is very useful when you are searching code for something. Doxygen is pretty popular. But there is no substitute for well written commentary on the why of your program. For that I still prefer using Sphinx for my work.

If you address all of these points, you are on your way to becoming a real programmer, one who will be welcomed into any team you might get a chance to join!

We will example the “right way” to write your code in our next lecture!