i program

The Many Faces of Simplicity

2008-05-20T09:42:00.000-07:00

There is an interesting series over at www.dev102.com called Programming Job Interview Challenge. They are at Challenge #4 already. You have to write a function foo which returns 17 if 7 is passed as parameter, 7 if 17 is passed as parameter.
You cannot use conditionals and containers of any kind.
And they say:

This is not a real world problem but it does check how simple can we think, so think - simplicity!

Simplicity... One of my favourite words.

So how do you transform 7 to 17 and 17 to 7 without conditionals and containers.

A Simple Idea
The first idea is that you should fix the tens in the passed parameter: if it is 0 make it 1, if it's 1 make it 0. (If it's other than 0 or 1, you can do whatever you like.

Wait... turning 0 to 1 and 1 to 0 is a logical negation thing... We could extract the tens, negate it and put it back. Simple enough.

Let's see:


int foo(int n)
{
 int tens = n/10;
 int ones = n-tens*10;
 int new_tens = !tens;
 int result = new_tens*10+ones;
 return result;
}

Hmmm... The idea is pretty simple, but the code is quite verbose. Let's try and remove some of the noise:


int foo(int n)
{
 return (!(n/10))*10+(n-10*(n/10));
}

Ok, now we have a single line, which is absolutely not readable. Simple idea, simple code, hard to understand.

Another Simple Idea

Let's see another approach. This time the idea is: if it's 7, add 10, if it's 17, substract 10.

Or rephrased: if it's seven, add 1*10, if it's 17 add (-1)*10.

So we just have to produce a 1 or -1 based on the tens:


int foo(int n)
{
 int tens = 2*(n/10);
 tens = tens - 1;
 return n - tens*10;
}

Compared to the first approach, the idea is a little bit more complex, but the code seems more simple. It is simpler measured some code complexity metric, but understanding what it does and how will be harder than the first one.

A Tricky Solution

As I was thinking about other solutions, bitwise operators came in my mind. Can we somehow manipulate the bits to get the solution we desire?

First, the numbers in binary:


07 = 00000111 
17 = 00010001

The idea is: we should find an operation which would flip the bits around until the correct result is produced. I remembered that there is something called XOR Swap which can swap two variables without the need of a temporary. This gave the idea of the next solution: use xor on the parameter to produce the desired result. What magical number would produce the desired result? Let's see the numbers again, and find the places where the bits do not match (marked with !):


07 = 00000111 
17 = 00010001
     ...!.!!.

If we take the 00010110 pattern and xor it with one of the patterns, it will produce the other pattern. Exactly what we need! So here is the code (binary 00010110 being 22 decimal):


int foo(int n)
{
 return n ^ 22;
}

This is the shortest code (being the simplest by code metric), but you would not find out what and how it does just by looking at the code. Also the idea of solving the problem is quite complicated.

And Finally: A Weird One

There is another variant of the tens-manipulation, which is simple in implementation, moderately complex in understanding:


int foo(int n)
{
 return n+10*((n==7)-(n==17));
}

Strictly speaking it conforms to the problem restrictions, however it can be considered that it violates the spirit of the problem statement, as (n == 7) is a boolean, which could be considered as a conditional.

Simplicity: Not That Simple

We saw 4 solutions to the same problem. One thing I observed is that there are more than one thing to be considered:
- the simplicity of the idea: how easy is to explain/describe how you solve the problem
- the simplicity of the code: using code some metrics, how many statements, branches etc. are in your code
- the readability of the code: how easy is to learn your intent just by reading the code

And these measures tend to change independently.

And all four solutions to the challenge proposed are acceptable. And they will be simple for one of the definitions above. And no one is better or worse absolutely than the others.

So, next time someone (possible me) will argue about a solution being simpler than another, I will look hard to see which simplicity we are talking about.

On errors and their handling

2005-09-19T03:18:00.000-07:00

I just found an enlightening article about errors and their handling by Herb Sutter in CUJ.

His clear definitions on what makes an error and how to handle them is most refreshing.

However it makes one wonder: isn't it strange that this error and error handling issue is still not clarified?

The article: When and How to Use Exceptions.

Another article which clarifies this thing (from the design-by-contract angle) is Bertrand Meyer's Applying "Design by Contract" (pdf). While Eiffel-oriented, it sets some pretty solid foundations on contracts, their violation and how to cope with those violations.

The beauty of it...

2005-08-11T08:50:00.000-07:00

While trying to wrap unmanaged C++ code in Microsoft's Managed Extensions for C++ I produced the following code:

return *(new Signal(&predictor->GetInputSignal(index)));

It hit me with it's Gaudi-esque beauty.

Simplicity

2005-06-22T06:53:00.000-07:00

Keep It Simple versus Make It Simple

Simplicity is hard.

Mentality: remove unnecessary cruft. This means you first add lots of things, then you have to discard them. That hurts.
Having a clear focus might help. Then you can ask questions like: removing this thing will hurt the focus?
Separate essential from auxiliary. A few essential points provide the most value. Auxiliary things add little value.

Commenting

2005-04-19T08:18:00.000-07:00

There is an article published in the ACM Queue titled Comments are more improtant than code.

After I first read, I was outraged. Being a supporter of self documenting, readable code, and a fan of extreme programming, I took the views of the author as a personal attack on me.

After a good nights sleep, the rage went away and the thinking process kicked in.

What's this commenting thing anyway?

We all know from the second program we ever write, that writing comments is not only good, is a necessity.

Reading the code written a month ago, and trying to recall the thinking process which led to a particular code is a painful experience.

It would be nice if we could just core-dump our thinking process right next to the code.

What can be in the code?

Lots of intent can be written in the code itself. Depending on the maturity of the programmer he can use names (class, method, member), patterns, idioms to capture a lot of static information about the structure, relationship, collaborations.

But there is so much more to know about the code. And this is where the comments can be a real help.

Tricky code & non-obvious solution comments

On the tricky parts (which are prime candidates to a healthy refactoring, according to XP proponents) one can explain the trick. But you better have a very good excuse for writing the tricky code.

If it is because the problem to be solved begs for a non-obvious tricky solution, then it's not only a good practice to write the comment explaining why the obvious solution won't work, it's mandatory. Otherwise the next programmer will inevitably come up with the obvious solution and waste his time finding out that it does not work.

If the trick is not mandated, the by all means take the XPers seriously and rewrite your code instead of commenting it.

Method comments

Sometimes pre and post-conditions can be expressed as assertions in the code itself, other times they can not be, or need extra explanations.

Method comments are the perfect place for this.

But writing method comments and not writing assertions where assertions are to be written, not throwing exceptions when exceptions are to be thrown is a bad thing.

Class comments

Explaining the goals of each class is the first and most oftenly misused form of comment.

Writing a comment in front of each class about what it's responsabilities are is not very useful. Given a good class (good class name, clear interface, suggestive names, method comments if needed) will render most of the comments redundant (see below other problems with redundant comments).

Most of the information often found in the class comments can be deduced from a good class. Poorly written classes need more explanation in the header, but it won't help understanding the code if one have to modify it.

Class relationship comments

The comments I often miss is the ones which explain the relationship and collaboration between several classes.

However where you put these comments? Placing them in the header of the classes involved is not very wise.

You better place them in separate text files, and add references to this text file in the header comments of the classes.

External constraints

Sometimes you have to explain an external constraint which influences your code (api, hardware, external components, bugs in libraries, etc).

If the influence is local (mostly in bugs) then your comments should be local too. For example if a call in an API has a particular local effect (for example the call will fail for parameter A having 42), you make the workaround and comment it locally.

However if the influence is not local, that is it influencess the design of your classes (often this is the case for facade components) then hiding the information in a local comment is bad.
Write a separate text file with the relevant information, and referr to this document in your code.
The references can be in the class comments and alos in code comments where you end up with non-obvious code (which cannot be refactored).

Combinations

Bad code with bad comments

How many times I saw code which was a complete mess? Hard to read, nearly impossible to understand. Usually crap like this is not commented, or the comments are themselves a shame.

Good code with bad comments

Sometimes I read clearly written code with crappy comments. The comments are redundant or misleading or both. When the code conflicts the comment, you are in trouble.

Good code with good comments

A few times I saw clearly written code with little or no comment. The comments were in their place and helped understanding better the code itself.

Bad code with good comments

I never saw bad code with good comments.

Conclusion

Writing good code is hard enough. It takes a lot of experience and lots of bad code written to get a grasp on wht is good code and how to write it.

Writing good comments is even harder and you cannot learn it until you get used to good code. As good code becomes the way you write code, you'll start writing less bad comment.

Code and comments are both good in communicating what you know.

Use both of them visely.

Todo
The readable code challenge

The readable comment challenge

Other ways to communicate
- knowledge bases
- wikis
- verbal communication

Reading list
- ACM Queue article
- Code Complete

whoami

2005-04-19T07:16:00.000-07:00

I program.

I program for a living and for fun.

I find great pleasure in exploring this infinitely flexible way of expressing myself.

I enjoy the creative hours spent on pet projects.

I enjoy the educative time spent reading books, articles.

I enjoy the passionate arguments I have with other programmers.

I consider the individual programmer as a craftsman.

I consider programming still a long way of becoming an engineering discipline.

I consider the future of programming at least as much fun and enjoyable as up until now.

I am glad I become a programmer.

I program.