I’ve been thinking about comments in code. Some people advocate not using comments suggesting that your code should be self documenting. I believe this to be a good practice where possible. If you need comments to explain what your code is doing, then it’s quite likely you’re code isn’t sufficiently broken down into lots of little methods naming what each part does. What happens when you have code that is simply non-intuitive and breaking it out into named methods doesn’t work?

Let’s look at an example to emphasize my point. We’ll take the naive Fibonacci function:

Now for a tail recursive implementation that is more efficient (but not in Python, as it doesn’t have tail call optimization! I should have done it in C, but I couldn’t face writing the tests using `check`).

I’ve tried my best to make this as self-explanatory as possible. I still feel that additional explanation would help for whoever has to maintain it. The first time I saw this definition `nth_fib` was `a` and `nth_minus_one_fib` was `b`, I had absolutely no idea how it worked. Naming things really makes such a difference!

• We only return `nth_minus_one` if `counter == 1`, which implies we’re calling `fib(1)` so we return the first fibonacci number: 0.
• When `n > 1` then `counter == 2` terminates the algorithm returning the accumulated value
``````  fib(3) -> fib_accumulator(3, 1, 0) -> fib_accumulator(2, (1 + 0), 1) -> return (1 + 0)