Index: libcfa/src/concurrency/barrier.hfa
===================================================================
--- libcfa/src/concurrency/barrier.hfa	(revision 93b8cf40f1dc4e4c569490157bff2a08be7c1534)
+++ libcfa/src/concurrency/barrier.hfa	(revision 31ef26735f46b5359d660de018c9a7f84beea961)
@@ -18,25 +18,39 @@
 #include <monitor.hfa>
 
+// Simple barrier based on a monitor
 monitor barrier {
-	int max;
-	int count;
+	// Number of threads blocking needed to unblock the barrier
+	// Unsigned should be enough, I don't expect use cases with 2^32 thread barriers.
+	unsigned width;
 
+	// Current count (counting backwards)
+	unsigned count;
+
+	// Barrier uses internal scheduling
 	condition c;
 };
 
-void ?{}( barrier & this, int max ) {
-	this.max = max;
-	this.count = max;
+// Constructor
+void ?{}( barrier & this, unsigned width ) {
+	this.width = width;
+	this.count = width; // Count backwards so initialize at width
 }
 
-static inline int block(barrier & mutex this ) {
-	this.count -= 1;
-	int arrival = this.count;
-	if(arrival != 0) {
+// block until the number of threads needed have blocked
+// returns an value indicating the reverse order the threads arrived in
+// i.e. last thread will return 0 (and not block)
+//      second last thread returns 1
+//      etc.
+static inline unsigned block(barrier & mutex this ) {
+	this.count -= 1; // prefix decrement so we the last is 0 and not 1
+	unsigned arrival = this.count; // Note arrival order
+	if(arrival == 0) {
+		// If arrived last unblock everyone and reset
+		signal_all(this.c);
+		this.count = this.width;
+	} else {
+		// Otherwise block
 		wait(this.c);
-	} else {
-		signal_all(this.c);
-		this.count = this.max;
 	}
-	return arrival;
+	return arrival; // return arrival order
 }
Index: tests/concurrent/barrier/generation.cfa
===================================================================
--- tests/concurrent/barrier/generation.cfa	(revision 93b8cf40f1dc4e4c569490157bff2a08be7c1534)
+++ tests/concurrent/barrier/generation.cfa	(revision 31ef26735f46b5359d660de018c9a7f84beea961)
@@ -15,7 +15,9 @@
 //
 
+// Test validates barrier by having each thread print ABCD...
+// If the barrier is correct it should print all As, all Bs, etc.
 
-int NUM_THREADS = 9;
-int NUM_LAPS = 53;
+unsigned NUM_THREADS = 9;
+unsigned NUM_LAPS = 53;
 
 #include <concurrency/barrier.hfa>
@@ -24,13 +26,24 @@
 #include <thread.hfa>
 
+// The barrier we are testing
 barrier bar = { NUM_THREADS };
+
 
 thread Tester {};
 void main( Tester & this ) {
+	// Repeat the experiment a few times
 	for(NUM_LAPS)
+		// For each letters
 		for(c; 'A' ~= 'Z') {
+			// Yield for chaos
 			yield(prng(this, 10));
+
+			// Print the generation, no newline because
 			mutex(sout) sout | c | nonl;
+
+			// Yield again for more chaos
 			yield(prng(this, 10));
+
+			// Block on the barrier
 			block(bar);
 		}
Index: tests/concurrent/barrier/order.cfa
===================================================================
--- tests/concurrent/barrier/order.cfa	(revision 93b8cf40f1dc4e4c569490157bff2a08be7c1534)
+++ tests/concurrent/barrier/order.cfa	(revision 31ef26735f46b5359d660de018c9a7f84beea961)
@@ -15,4 +15,7 @@
 //
 
+// Test validates barrier and block return value by checking
+// that no more than one thread gets the same return value
+
 #include <concurrency/barrier.hfa>
 #include <fstream.hfa>
@@ -20,24 +23,37 @@
 #include <thread.hfa>
 
-const int NUM_LAPS = 173;
-const int NUM_THREADS = 11;
+const unsigned NUM_LAPS = 173;
+const unsigned NUM_THREADS = 11;
 
+// The barrier we are testing
 barrier bar = { NUM_THREADS };
-volatile int * generation;
+
+// The return values of the previous generation.
+volatile unsigned * generation;
 
 thread Tester {};
 void main( Tester & ) {
+	// Repeat a few times
 	for(l; NUM_LAPS) {
-		int ret = block(bar);
-		int g = generation[ret];
+		// Block and what order we arrived
+		unsigned ret = block(bar);
+
+		// Check what was the last generation of that last thread in this position
+		unsigned g = generation[ret];
+
+		// Is it what we expect?
 		if(g != l) {
+			// Complain that they are different
 			sout | "Gen" | l | ": Expeced generation at" | ret | "to be" | l | "was" | g;
 		}
-		generation[ret] = g+1;
+
+		// Mark the expected next generation
+		generation[ret] = l+1;
 	}
 }
 
 int main() {
-	volatile int gen_data[NUM_THREADS];
+	// Create the data ans zero it.
+	volatile unsigned gen_data[NUM_THREADS];
 	for(t; NUM_THREADS)
 		gen_data[t] = 0;
@@ -45,4 +61,5 @@
 	generation = gen_data;
 
+	// Run the experiment
 	processor p[4];
 	{