Robert Martin (die ook schrijft onder de naam Uncle Bob) is een geweldige spreker en een wereldberoemd schrijver van publicaties over software craftmanship. Hij is dermate gepassioneerd over het op een hoger niveau brengen van ons vak, dat hij zelfs voor een groepje jonge engineers die de schoolbanken nog niet hebben verlaten een vlammend betoog komt houden.

Hij raasde in een uur tijd door zijn slides over Clean Code heen, lardeerde dat met leuke verhalen en analogieën en onderbouwde zijn betoog met praktijk voorbeelden. Hieronder een greep uit de tips die we kregen over het schrijven van functies.

Leesbaarheid

Eigenlijk gaan alle onderstaande tips over de leesbaarheid van de code. Iemand die jouw code ziet (en dat kun je ook goed zelf zijn) moet met lichte verveling van boven naar beneden door je code kunnen gaan, waarbij de code steeds gedetailleerder wordt.
- “Ja”
- “Mmmh, mmh”
- “Duidelijk”
- “Ja”
- “Logisch”
Totdat de code een nivo van detaillering bereikt dat je als lezer denkt “Ja, ja, nu begrijp ik het wel. Saai”. Dan heb je het goed gedaan. Saaie code, waar niemand lang bij hoeft stilt te staan (want daar heb je gewoon geen tijd voor). Niemand zit te wachten op briljante code, behalve jouw ego. Briljante code is de eerste code die ik vervang als ik onderhoud moet doen; vervang door saaie, begrijpelijke code.

Descriptive names

Gebruik een naam voor je functie die zegt wat de functie doet. Dus niet “Process()” maar “AddOrderLineToOrder()”.

Do One Thing

Een functie moet slechts 1 ding doen. Als een functie 2 dingen doet, moet je ‘m in 2 functies opdelen. De functie “AddOrderAndCalculateTotals()” wordt dan dus “AddOrder()” en “CalculateTotalsForOrder()”.

Small functions

Functies mogen niet meer dan 4 regels lang zijn (tussen de accolades). Het liefst 2 of 3, maar als het echt moet dan kan 4 ook. Een functie moet eigenlijk niet veel meer doen dan bijvoorbeeld een test uitvoeren in een if-statement en dan een andere functie aanroepen. En de test in de if is natuurlijk ook een functie.
Hoe kom je aan kleine functies? Die kun je niet van scratch af aan maken. Je maakt eerst je bekende grote bak code van wel 20 of 30 regels, zodat je je test aan de praat kan krijgen (je weet wel “Red-Green-Refactor”). Daarna ga je je grote functie opknippen met een van de standaard Refactor-tools die jouw IDE ondersteunt, meestal “ExtractMethod” geheten. En na elke ExtractMethod draai je je tests om te weten of je niets stuk gemaakt hebt.

No error codes

Functies moeten exceptions gebruiken en try/catch blocks. Binnen een try moet bij voorkeur 1 regel code staan: de aanroep van een functie.
Return-codes zijn om iets nuttigs terug te geven aan de aanroepende code, bijvoorbeeld een Boolean als je functie “IsValidDate()” heet, maar niet om te laten weten dat er iets is mis gegaan. Error-codes leiden tot veel geneste if’s en tot out-parameters (zie verderop).

No more than 3 parameters

Een functie heeft bij voorkeur geen parameters, dat leest het makkelijkst, maar is niet zo realistisch. Als een functie meer data dan 3 parameters nodig heeft om zijn werk te kunnen doen, moet je gaan refactoren. Waarschijnlijk hoort al die data bij elkaar in één class.

No out-parameters and no boolean-parameters

Een functie heeft dingen aan de rechterkant (parameters) die erin gaan en een ding aan de linkerkant (return-value) die eruit komt. Als er dingen aan de rechterkant uitkomen verwar je de lezer enorm. Tijd voor een refactoring.
Booleans lezen helemaal moeilijk en verraden dat je eigenlijk een functie hebt die 2 dingen doet, gestuurd door de vlag die je erin stop.
Wat doet het onderstaande?

var html = GetHtmlForControl(button, true)

Zou het niet beter zijn om 2 functies te hebben die beter laten zien wat ze doen?

private string GetUnformattedHtmlForControl(button)
{ ... }
private string GetFormattedHtmlForControl(button)
{ ... }

Unit tests

Als je geen unit-test hebt kun je nooit bewijzen (voor jezelf, je teamgenoten of je baas) dat de code die je gemaakt hebt echt werkt.
Accountants controleren hun eigen werk door elke boeking 2 keer op te nemen: één keer aan de debet kant en één keer aan de credit kant. Onderaan moet dan nul staan. Je kunt nog steeds de pech hebben dat je twee fouten hebt gemaakt die elkaar precies opheffen, maar die kans is niet zo groot. In ieder geval heb je een Standard Practice toegepast.
Dat kunnen wij software-engineers minstens even goed doen. Code schrijven en tests schrijven.

Design Patterns

Ken je patterns. Het boek van de Gamma et al is volgens Robert Martin het belangrijkste boek dat de afgelopen 20 jaar is geschreven op het gebied van software design.

Maar daar hebben we geen tijd voor!

Je zult het zelf misschien onmiddellijke roepen als je bovenstaande hebt gelezen: “Allemaal leuk en aardig, en ja, ik wil goeie code schrijven, maar het moet af, ik heb hier echt geen tijd voor”.
Fout. Als je het op bovenstaande manier doet, houd je tijd over. Om de simpele reden dat iedereen gedurende het project zijn bestaande code moet uitbreiden, aanpassen, verbeteren of overdragen. Als je clean-code schrijft dan kost dat wroeten in je eigen code je veel minder tijd dan wanneer je de gebruikelijke bak spaghetti heb geschreven. En omdat je unit-tests hebt, weet je ook dat je aanpassing niets stuk gemaakt heeft.

Robert Martin haalde het voorbeeld aan van Hongaarse arts Ignaz Semmelweis die ontdekte dat het aantal vrouwen dat overleed in het kraambed van 8 op de 10 zakte naar 1 op de 100 als je eerst je handen waste nadat je een autopsie had gedaan. Hij begreep niet waarom, maar stelde onomstotelijk vast dat het werkte. Desalniettemin duurde het tot vele jaren na zijn dood voordat deze activiteit tot het standaard repertoire van de arts ging behoren.

Zou jij tegen je chirurg zeggen vlak voordat je de operatiekamer ingereden werd “Laat dat handen wassen maar achterwegen hoor, daar heb je helemaal geen tijd voor”? Vast niet. En omgekeerd? Als jouw patiënt dat zou zeggen, zou je dan naar hem luisteren?
In jouw vak ben jij de chirurg en is je opdrachtgever degene die onder het mes gaat.

Word een professional

Wij zijn geen loonwerkers, ons werk is niet te vergelijken met het op elkaar stapelen van stenen. En onze verantwoordelijkheid gaat verder dan “maar hij heeft gezegd dat dat zo moest”. Als professional heb je de plicht om tegen je opdrachtgever/klant/baas “nee” te zeggen als hij/zij vraagt om iets slechts af te leveren.
- “Kun je het niet zonder tests?”
- “Nee”
- “Maar daar hebben we geen tijd voor!”
- “Dus er mogen bugs zitten in mijn werk?”
- “Uh, nou ja, het hoeft niet perfect te zijn”
- “Als er bugs in mogen zitten, dan ben ik klaar wanneer je wilt. Nu al, feitelijk”
- “Kom op, je begrijpt best wat ik bedoel”
- “Nee, wil je nou dat ik m’n handen was of niet?”
- …..?

Get SOLID

There are two things that I always try to keep in mind when making software: loose coupling and tight cohesion. In other words:

1. make sure your classes don’t know things that they don’t need to know
2. make sure your classes are good at one thing and one thing only

These guidelines are part of the 5 SOLID principles of class design by Uncle Bob Martin:

1. Single Responsibility Principle
2. Open Closed Principle
3. Liskov Substitution Principle
4. Interface Segregation Principle
5. Dependency Inversion Principle

This stuff is really interesting and sort-of scientific, but it is also like making your database comply to the 5-th Normal Form: nobody does that. You’re happy with a 3rd Normal Form database. So I’m happy when I see code that complies with at least two of the above principles.

So what I do when building my iPhone apps is constantly asking myself: should this code be in this place? Sometimes I know right away that the answer is No, but still leave it there until I have a better idea on where to put it then. And with the (for me) rather unusual structure that the Cocao Framework forces upon me, it may take some time before I eventually find out where to put it.

Let me give you an example.

When you want to load data into a UITableView you must create a UITableViewDataSource and assign that to the DataSource property of your UITableViewController. Like this:

public override bool FinishedLaunching (UIApplication app, NSDictionary options)
{
	tableView.DataSource = new LeesPlankjeDataSource();
	window.AddSubview (tableView);
	window.MakeKeyAndVisible ();
	return true;
}

The class instantiated at line 3 is something like this:

public class LeesPlankjeDataSource : UITableViewDataSource
{
	private string[] woordjes = new string[] {"aap", "noot", "mies"};
	public override UITableViewCell GetCell (UITableView tableView, MonoTouch.Foundation.NSIndexPath indexPath)
	{
		UITableViewCell cell = tableView.DequeueReusableCell("plankje");
		if (cell == null)
		{
			cell = new UITableViewCell(UITableViewCellStyle.Default, "plankje");
		}
		cell.TextLabel.Text = woordjes[indexPath.Row];
		return cell;
	}
 
	public override int RowsInSection (UITableView tableview, int section)
	{
		return woordjes.Length;
	}
}

On line 3 you see the actual “data store”, and on line 4 an important override. This method gets called by Cocoa when loading data in your UITableView. So the controller has a data source and the appropriate methods get called by the framework.

On to a more realistic implementation

If I want to advance my class a bit, I could imagine that the data is not a fixed array of strings, but gets passed in at construction time. Maybe I read from a file or from a URL.

That changes my class to this:

public class LeesPlankjeDataSource : UITableViewDataSource
{
	private string[] _dataStorage;
 
	public LeesPlankjeDataSource(string[] data)
	{
		_dataStorage = data;
	}
 
	public override UITableViewCell GetCell (UITableView tableView, MonoTouch.Foundation.NSIndexPath indexPath)
	{
		UITableViewCell cell = tableView.DequeueReusableCell("plankje");
		if (cell == null)
		{
			cell = new UITableViewCell(UITableViewCellStyle.Default, "plankje");
		}
		cell.TextLabel.Text = _dataStorage[indexPath.Row];
		return cell;
	}
 
	public override int RowsInSection (UITableView tableview, int section)
	{
		return _dataStorage.Length;
	}
}

And the main.cs gets these lines:

	string[] woordjes = File.ReadAllLines("woordjes.txt");
 
	tableView.DataSource = new LeesPlankjeDataSource(woordjes);

Make sure when you have files that you want to be deployed with your app to set the build-action on the file to “content”:

That’s all neat. The DataSource gets it data from the outside and doesn’t care if it comes from a file or a network-connection.

So now we want some action when the user taps a row. You have no choice but to implement this in a delegate (a UITableViewDelegate of course) and then override the RowSelected() method. This method is called for you by Cocoa and as parameters you get a UITableView that the tapping happened on and the Row number that was tapped:

public class LeesPlankjeViewDelegate : UITableViewDelegate
{
	public override void RowSelected (UITableView tableView, MonoTouch.Foundation.NSIndexPath indexPath)
	{
	}
}

But what can I do in this method? Let’s say I want to do a MessageBox-ish thing to show what word was chosen. All I have is an index to the row in my data source. But I don’t have the data source itself in this class. I need some way to acces my original data store.

I could do somehting like this:

public override void RowSelected (UITableView tableView, MonoTouch.Foundation.NSIndexPath indexPath)
{
	string message = tableView.DataSource.GetCell(tableView,  indexPath).TextLabel.Text;
	using (var alert = new UIAlertView ("", message, null, "OK", null))
	{
		alert.Show ();
	}
}

So I ask the TableView for its data source, then ask the data source to give me the cell that is on the given index, and then ask the cell for the text of the label. It works, but it is butt-ugly. Why? Because now the delegate knows about the data source too. And I think it shouldn’t, because all the delegate needs to do is handle UI-interactions from the user. It should say “Hey, someone tapped me on this row, do something with it” and then leave the actual work to someone else.

I think it would be reasonable to leave the work to the controller. For me, a controller is always the man-in-the-middle, doing the real work brokering between the model and the view. But if I choose that, I have to pass in the controller when constructing the Delegate, like this:

tableView.Delegate = new LeesPlankjeViewDelegate(tableViewController);

And since the tableViewController is only known so far in the Interface Builder, I have to make the controller available in my code by creating an outlet. Sigh…. even more code in my FinishedLaunching() method. I don’t want that, I want to hook up UI-parts with each other using the Interface Builder, not in code.

So, what to do now? I don’t know yet. Let me first deal with a problem that I didn’t tell you about yet. It is in the code of the LeesPlankjeDataSource. I gave my LeesPlankjeDataSource a constuctor that accepts a string array, thereby enabling me to pass in the data that the data source needs to build a UITableView from.

The problem is, that the UISearchDisplayController re-uses my UITableViewController, including the DataSource. When I click search, it first simply overlays my view, but when I start typing in the search box, the ShouldReloadForSearchString () method gets called and that one resets the SearchResultDataSource with a filtered version of my LeesPlankjeDataSource:

public override bool ShouldReloadForSearchString (UISearchDisplayController controller, string forSearchString)
{
	Console.WriteLine("In ShouldReloadForSearchtring");
	controller.SearchResultsDataSource = new LeesPlankjeDataSource(forSearchString);
	return true;
}

And how am I gonna feed this baby with the right data? How is the SearchResultsDataSource going to get a filtered list of the words in my “woordjes.txt” file? I chose to filter by using an overloaded constructor, but I could move that code to a normal method. That allows me to use the other constructor, passing in the data as before in the main.cs:

public override bool ShouldReloadForSearchString (UISearchDisplayController controller, string forSearchString)
{
	Console.WriteLine("In ShouldReloadForSearchString");
	var woordjes = ?????????
	var data = new LeesPlankjeDataSource(woordjes);
	controller.SearchResultsDataSource = data.FilterOn(forSearchString);
	return true;
}

But where am I gonna get the “woordjes” variable from? Should I load the file again, like I did in main.cs? Or maybe my DataSource should know something about the model? In that case I will not pass data from the outside, but let the DataSource find out itself where to get the data. But that is so against the Dependency Inversion Principle (or Inversion of Control)! If classes depend on other classes, these dependencies had best be passed in from the outside, probably on construction time.

Shoot, I love the IoC pattern. Should I let it go, for the sake of simplicity? After all, I argued before that even the MVC-pattern was maybe to much of a burden for the simple applications we build on the iPhone most of the time.

For tonight, I give up. The code you can download contains the solution that goes against IoC, but works none the less.

I would love to hear your ideas about how to build iPhone applications that are tightly coherent and loosely coupled. I know that we can get in some philosophical or religious discussions, but we’ll see what to do then. I just want to learn from you guys, as much as I want to teach you where I can.

P.S.
Thanks to Alex York’s excellent post (see his comment below) I was able to improve on my code. I had seen the idea of nesting the DataSource and Delegate into the UITableViewController before, but didn’t like it then. That dislike mostly came from the fact that you have to inherit from another class. There is no tighter couling between two classes then inheritance, so I believe you should only use it when absolutely necessary. Well, by now I think that it is absolutely necessary to inherit from the classes in the Cocoa framework. It is simply the way you work.

When working on the new solution I also renamed some classes (no more Dutch names, only Dutch words in the data…) and added a class that implements the model:

public class WordsModel
{
	private List _dataStorage;
 
	public WordsModel ()
	{
		_dataStorage = File.ReadAllLines("woordjes.txt").ToList();
		_dataStorage.Sort();
	}
 
	public string[] Data {
		get { return _dataStorage.ToArray();}
	}
 
	public string[] FilterOn(string searchText)
	{
		searchText = searchText.ToLower();
		var result = _dataStorage.Where(t => t.ToLowerInvariant().StartsWith(searchText));
		return result.ToArray();
	}
}

It is the place where the knowledge of words, where they come from and how you filter them, resides.

But Alex’s solution did not solve the problem that is typical of the use of the UISearchDisplayController: you have two instances of your DataSource: the one for your initial view, that just displays all the data (words in my case), and the one that is called upon by the UISearchDelegate when you start to search and filter.

I solved this by implementing a general WordsDataSource that uses the WordsModel and has a constuctor for normal use and for filtering:

public class WordsDataSource : UITableViewDataSource
{
	private WordsModel model = new WordsModel();
	private string[] _dataStorage;
 
	public WordsDataSource()
	{
		_dataStorage = model.Data;
	}
 
	public WordsDataSource(string filter) : this()
	{
		_dataStorage = model.FilterOn(filter);
	}
 
	public string GetAt(int position)
	{
		return _dataStorage[position];
	}
 
	public override UITableViewCell GetCell (UITableView tableView, MonoTouch.Foundation.NSIndexPath indexPath)
	{
		UITableViewCell cell = tableView.DequeueReusableCell("plankje");
		if (cell == null)
		{
			cell = new UITableViewCell(UITableViewCellStyle.Default, "plankje");
		}
		cell.TextLabel.Text = _dataStorage[indexPath.Row];
		return cell;
	}
 
	public override int RowsInSection (UITableView tableview, int section)
	{
		return _dataStorage.Length;
	}
}

It inherits (yep I used the I-word) from UITableViewDataSource so can be called upon by the Cocoa framework when rendering the data for the UITableView.

And then I used that class in two places:

1. as an internal property in my WordsTableViewController
2. as a helper-class in the delegate of the UISearchDisplayController.

[MonoTouch.Foundation.Register("WordsTableViewController")]
public partial class WordsTableViewController : UITableViewController
{
    // Constructor invoked from the NIB loader
    public WordsTableViewController (IntPtr p) : base (p)
    {
    }
 
    // The data source for our TableView
    private WordsDataSource TableDataSource
    {
	get { return this.TableView.DataSource as WordsDataSource; }
	set { this.TableView.DataSource = value; }
    }
 
    // This class receives notifications that happen on the UITableView
    class TableDelegate : UITableViewDelegate
    {
	WordsTableViewController parentView;
        public TableDelegate (WordsTableViewController tableViewController)
        {
		parentView = tableViewController;
        }
 
        public override void RowSelected (UITableView tableView, NSIndexPath indexPath)
        {
		string selectedWord = parentView.TableDataSource.GetAt(indexPath.Row);
		using (var alert = new UIAlertView ("Selected", selectedWord, null, "OK", null))
			alert.Show ();
        }
    }
 
    public override void ViewDidLoad ()
    {
        base.ViewDidLoad ();
 
        TableView.Delegate = new TableDelegate (this);
        this.TableDataSource = new WordsDataSource ();
    }
}

[MonoTouch.Foundation.Register("WordSearchDelegate")]
public class WordSearchDelegate : UISearchDisplayDelegate
{
	public override bool ShouldReloadForSearchString (UISearchDisplayController controller, string forSearchString)
	{
		UITableViewDataSource data = new WordsDataSource(forSearchString);
		controller.SearchResultsDataSource = data;
		return true;
	}
}

I’m pretty happy with what I got by now. You can download the new version, if you like.