Writing Stupid Code

A surprisingly good idea

In this course, I am going to encourage you to write "stupid code" rather than "clever code" or "enterprise-class" code.

Definition

Stupid Code is code that you will be able to understand and work with three years from now when you are scrambling to fix a bug; even at 3am before a submission deadline; and even on a borrowed laptop.

The Principles of Stupid Code

Stupid code tends to follow a few basic principles:

• Locality. Put it all in one place.
• Paranoia. Check everything. An 'assert()' is more valuable than a comment.
• Laziness. Do only what needs doing. If it needs to go faster or be extended, you can re-write it later.
• Minimize dependencies, both on libraries and build tools. The standard library is powerful.

Locality

Locality is your most powerful tool for writing stupid code. When you need to understand code, it is very useful to have all of the code you need to understand in one place, clearly arranged.

Thankfully, C++ has some great features that can help you achieve locality.

Scopes

The most powerful feature for working with locality in C++ is scoping. Whenever you see { int x; ... } you know that whatever is within the brackets is going to be a unit of functionality *and* that whatever the variable x is doing, it isn't going to be used outside of that chunk.

Also, if you use the RAII ("resource allocation is initialization") paradigm -- and I encourage you to do so -- scopes show when certain resources are active.

	{ //draw badges
		UseProgram use(ui_tex_prog);
		BindTexture bind0(GL_TEXTURE0, badges_tex);

		GLuint attrib_Position = ui_tex_prog("Position");
		GLuint attrib_TexCoord = ui_tex_prog("TexCoord");

		badge_verts.VertexAttribPointer(attrib_Position);
		badge_texcoords->VertexAttribPointer(attrib_TexCoord);

		EnableVertexAttribArray enable_position(attrib_Position);
		EnableVertexAttribArray enable_texcoord(attrib_TexCoord);

		ui_tex_prog["scale"] = BigRad;
		ui_tex_prog["tint_color"] = tint;

		ui_tex_prog["translate"] = glm::vec2(col_mid, badge_y);
		glDrawArrays(GL_TRIANGLE_STRIP, 0, badge_verts.count);
	}

Get in the habit of throwing a comment in the first line of a scope to make it clear what's going on.

Let me call out RAII once more. Very useful for making it so you never forget to write clean-up code.

struct GLTexture {
	GLTexture() { glGenTextures(1, &tex); }
	~GLTexture() { glDeleteTextures(1, &tex); tex = 0; }
	GLuint tex = 0;
}

Lambdas

Lambdas (local functions) in C++ give you a great way to encapsulate and re-use local scopes without breaking the flow of the code.

Quick lambda refresher:

	auto func = [/*capture*/](/*params*/){
		/*body*/
	};

• func is the variable that names the lambda. Declared auto because the compiler gets to know what type it is. Think of it as an opaque function pointer that also contains a reference-counted block of captured parameters. Even though the type of a lambda can't be written explicitly, you can use std::function<> to hold them.
• capture tells the compiler which variables from the containing scope can be touched by the inner scope.
• params are the function parameters.

Example: you just finished writing this nice interpolation function:

void Title::update(float elapsed) {
	t += elapsed; //accumulate time
	//fade in the main title:
	if (t < 0.5f) {
		main_color.a = 0.0f;
	} else if (t < 1.5f) {
		main_color.a = (t - 0.5f) / (1.5f - 0.5f);
	} else {
		main_color.a = 1.0f;
	}
}

And now you want to add a subtitle:

void Title::update(float elapsed) {
	t += elapsed; //accumulate time
	auto fade = [&t](float t0, float t1, float *alpha) {
		if (t < t0) {
			*alpha = 0.0f;
		} else if (t < t1) {
			*alpha = (t - t0) / (t1 - t0);
		} else {
			*alpha = 1.0f;
		}
	};
	//fade in titles:
	fade(0.5f, 1.5f, &main_color.a);
	fade(0.8f, 1.8f, &sub_color.a);
}

Example: say you want to sort some data by a particular key:

struct Player {
	glm::vec2 position;
	float score;
};
std::vector< Player > players;

//sort players by score:
std::sort( players.begin(), players.end(), [](Player const &a, Player const &b) {
	return a.score < b.score;
});

Inline Structures, Initializers

Two different features that go together well.

Group together related variables in a clean way (also great when debugging):

struct {
	float speed = 1.0f;
	std::string title = "racer-x";
} config;

Great for temporary transformations of data:

struct Range {
	Range(uint32_t index_, int32_t min_, int32_t max_) : index(index_), min(min_), max(max_) { }
	uint32_t index;
	int32_t min, max;
	bool marked = false;
};
std::vector< Range > ranges;
for (auto const &sprite : sprites) {
	ranges.emplace_back(&sprite - &sprites[0], sprite.x - sprite.r, sprite.x + sprite.r);
}
//...

Static variables

In many cases -- especially when working with OpenGL -- you want a resource that is initialized once, but putting it at the global scope is wrong for a number of reasons. The static keyword helps with this.

void draw() {
	//really bad (leaks buffer):
	GLuint buffer = 0;
	if (buffer == 0) {
		/*initialize buffer*/
	}
	//fine (but not a great habit, for subtle reasons):
	static GLuint buffer = 0;
	if (buffer == 0) {
		/*initialize buffer*/
	}
	//superb:
	static GLuint buffer = []() -> GLuint {
		GLuint buffer = 0;
		/*initialize buffer*/
		return buffer;
	}();
	//...
}

Note that static variables used in this way tend to work against failing early (see below), so there is a balance to be struck here!

Paranoia

Paranoia -- in the coding sense -- means stating what you know clearly. C++ gives you some great ways to do this: types, assert, and static_assert.

Types

Variable types are an easy way to help understand a program. Seeing Image i; vs int i; is going to be very informative.

Basic tips for type sanity:

• Unsigned is amazing. Use it for loop indices.

  for (uint32_t i = container.size() - 1; i < container.size(); --i) {
  	//even for reverse loops! Really!
  }

• The sized integral types (i.e. uint32_t) are compact and convenient, especially when doing I/O. It makes it clear what size and signedness of integer you've got. (Note that glm provides nice sized vector types as well.)
• const is also amazing. Keep in mind that it actually *guarantees* nothing, but it is a great reminder.

  const int Count = 15; //Make it clear that Count shouldn't change
  void shuffle_copy(const std::vector< int > &from, vector< int > *to) {
  	//it's pretty clear that 'from' shouldn't be changed
  	//... though keep in mind that there is nothing preventing "from" and "to" from aliasing
  }
  

• Related to the previous example, I am coming to enjoy the "use * to mean output argument" style of function call. It isn't as elegant as (e.g.) the C# 'out' keyword, but it is a step in the right direction.
• Use auto sparingly. When you use auto instead of explicitly writing a type, you are giving up a chance to make the code more understandable. Only write auto when the type is obvious and would be cumbersome. I.e.:

  //Good use of auto:
  auto iter = container.begin();
  //without auto:
  std::vector< std::pair< int, float > >::iterator iter = container.begin();

• Smart pointers are stupid-code compatible because they tell you about pointer ownership expectations. (std::unique_ptr says "mine, and mine only", while std::shared_ptr says "here be complex reasoning")
• When you have a pointer-not-null coerce it to a reference. (Relatedly: ensure that references are pointers-not-null.)

  void step_particles(std::vector< Particle > const &in, std::vector< Particle > *out_) {
  	assert(out_ && "output array is required.");
  	auto &out = *out_; //(note: debatable use of auto)
  	/* ... */
  }

• Be careful with typedefs. They can obscure important information.

Assert

Never Write An Assert Than Should Fail

i.e. "don't use assert() to check data errors, use it to check programming errors"

(For data errors, I recommend throwing std::runtime_error or -- if you are feeling oldschool -- exit(1).)

//bad assert: [bad data file can cause assert()]
	std::vector< glm::vec3 > normals = load_normals_from_file();
	for (auto const &n : normals) {
		assert(n != glm::vec3(0.0f, 0.0f, 0.0f) && "normals shouldn't be zero-length");
	}
//good assert: [loading routine establishes invariant; assert() checks it later]
	std::vector< glm::vec3 > normals = load_normals_from_file();
	for (auto const &n : normals) {
		if (n == glm::vec3(0.0f, 0.0f, 0.0f)) {
			std::cerr << "ERROR loading file: found a zero-length normal." << std::endl;
			return;
		}
	}
	/* ... code that preserves non-zero normals goes here */
	for (auto const &n : normals) {
		assert(n != glm::vec3(0.0f, 0.0f, 0.0f) && "normals can't be zero-length or file loading wouldn't have succeeded");
	}

Note that this is a fuzzy line. You will need to make judgement calls as to whether, e.g., errors in the contents of data files written by your code are covered by assert(). You probably won't actually care in these fuzzy cases; so just pick an option.

Asserts Are Comments You Can Trust

Consider making them more helpful by including a && "description of problem" in the parameter. This will get printed when the assert fails, which can jump-start your debugging process.

At the very least, place a comment near the assert justifying why it will never fail.

assert(pos[i].x <= pos[i+1].x && "pos array is always sorted in x-coordinate.");
//or:
assert(pos[i].x <= pos[i+1].x); //pos array is always sorted in x-coordinate.

Other Important Stuff

• MSVC has a bad habit of turning asserts off in Release builds. You will almost certainly want to be testing your code in release mode all of the time, so make sure that the macro NDEBUG isn't being defined by a command-line flag. (see MSDN.)
• Don't put things with side-effects in your asserts(). If you do ever decide to not compile them the missing side effects will confuse you.
• Wrap more complicated checks in #ifdef PARANOIA or similar, toggle as needed.

Static Assert

A special assert that checks at compile time, rather than runtime. Very useful when, e.g., making sure that structures are packed.

struct Color {
	uint8_t r,g,b,a;
};
static_assert(sizeof(Color) == 4, "Color is packed as expected.");

Fail Early

With all this talk of runtime errors, it's worth thinking for a moment about *when* you want runtime errors to trigger. That is, ideally, as soon as possible.

This comes up especially with resource loading. Consider a missing texture in the final cutscene of the game. You want to find out about this ASAP rather than after playing through the entire experience.

void init() {
	intro_texture = load_texture("intro_texture.png");
	level_texture = load_texture("level_texture.png");
	final_texture = load_texture("final_texture.png");
}
void draw_final_scene() {
	draw_texture(final_texture);
}

Of course, this breaks when you start having more assets than you have memory to work with; in which case you may still wish to have some notion of a streaming asset handle and a special mode that makes sure that all handles connect to real assets.

Laziness

Do only what needs doing.

Corollary: always write code for an immediate reason.

Corollary: don't optimize until you've profiled.

Corollary: do things the easy way first.

Minimize Dependencies

Pick a compiler for each platform. I recommend:

• Windows: cl.exe (the microsoft C++ compiler shipped with Visual Studio).
• OSX: clang++ (the apple-supported compiler shipped with XCode).
• Linux: g++ (the GNU compiler collection C++ compiler).

Compiling with three different tools should -- one hopes -- give one three different sets of static checks, ensuring better code quality.

Pick a way to call that compiler on each platform. You'll want something explicit in its build steps and easy to remember how to run:

• I recommend ft-jam. Very easy to make it do exactly what you want. Cross-platform.
• Just writing all the build steps longhand (in shell or python or cmd.exe) isn't a terrible idea either. A bit more work than jam, but very clear.
• Avoid "make" for building code. The lack of dependency-scanning makes it dangerous in an incremental-build situation. Though it's pretty good for asset pipelines.
• Avoid enterprise-class build systems (e.g. CMake). They tend to bit-rot and require a lot of environmental control to set up and validate.
• Maintaining a per-os IDE project is also a valid solution, though somewhat cumbersome in early development.

The Standard Library

The standard library in C++ is really, really good. It will save you a lot of work.

Things you should make sure you are aware of (and should use as needed):

• The templated containers. Especially vector, dequeue, and list. And the associative containers map, set, unordered_map, and unordered_set. Make sure you have a mental model of these containers.
• The generic algorithms in algorithm mix nicely with templated containers. sort (note: stable_sort) and reverse will do a heck of a lot for you. Also, I guess, push_heap and pop_heap.
• Remember chrono for time-related functions, including high-precision and high-performance clocks.
• Remember random for std::mt19937 -- for deterministic pseudo-random number generation. [Caveat: avoid distributions.]
• For threaded programming, thread and atomic are both really convenient as well.

Other Notes

Use #pragma once in headers instead of #ifdef wrapping.

Stick to a coding style. I prefer:

• lowercase_with_underscores for local variables and parameters.
• CapitalCase for class/struct names.
• ALL_CAPS for macros.
• Almost always use indented blocks for if statements.
• Always comment closing brackets of namespaces and #ifdefs
• In aggregate types, make sure that all members are initialized (either inline, or in constructor).

Remember that using tab characters for indentation reaffirms the intrinsic goodness and diversity of humanity. So just do it.