Get Rid of Your Retrospective Meetings Once and for All

Agile Retrospective Meetings...  Sounds boring, right?

And you're correct. They usually are. They don't give you the results you're looking for. Instead, they waste people's time and energy.

Readable Code Instead of Comments

I remember my C++ teacher arguing strongly that all code should be commented and you should never hesitate to add comments. "When in doubt: comment!". I did not agree with him then, and I do not agree with him now. With experience, I have come to realize that comments in high level language code is rarely needed. I won't go so far as to say that writing comments are a failure, but its pretty close.

Readable code is self-documenting code!

A comment followed by a block of code can often be replaced by a method which states the intent just as well as the comment, and makes the code more modular and reusable. 

• It makes refactoring happen more often.
• It helps us write readable code. Readable code is a joy to work with.
• It tends to make methods short and sweet.
• It avoids comments getting out of sync with the code
• It challenges you to rewrite commented code that is hard to understand.

Apart from the cleanliness of the code, there are a number of others problem with having comments in the code as well. Number one problem being that comments does not automatically change with the code. You end up with comments that disagrees with the actual program, which leads you on a wild goose chase spending lots of energy trying to figure out what is going on. I rarely read in-line comments for this reason and when I do, I always have to assume they are wrong. 

Note that I am talking about in-line comments primarily. There are situations where comments have its uses. For example, to provide an overview of a class or module, to reference external documentation or maybe to explain the rationale for a workaround in the code.

When I see comments in code, I think of them as personal challenges: 

Can I remove that comment and make the code more readable? 

Try it yourself next time!

Here are some mostly real life examples of comment problems I've come across. I used these snippets in a code quality workshop I ran for a client:

Readable Code

I've been working as a developer a good number of years. During those years, I have seen my share of good code and bad code. Some of it written by myself (good and bad I might add...). But we learn from our mistakes, and eventually principles, dos and don'ts gets integrated into the way we code, hopefully into something great.

I still struggle somewhat with analysis paralysis, but my best remedy for that is to go back to the core of agile and focus on what is needed right now. TDD helps a lot as well. Agile practices are great for keeping the code slim and to the point, but that alone is not enough for producing good code. So I'd like to spend some time writing a bit about what I think good and bad code looks like.

First, I believe code should be written as prose, with the primary intent that other humans should be able to easily read and understand it. The reasoning is that code is read a lot more often than it is written. This simple sentiment makes it obvious that code must be easy to digest, so it is worth spending some time now making your code readable, to save lots of frustration later. I loathe having to read and re-read the same code chunks again and again until I understand what it does, only to realize I was looking in the wrong place and have to go search somewhere else to fix it.

Clean, readable code is a joy to read and it serves as good examples for others as well. Programmers, especially juniors, learn a lot from reading code and it is natural to mimic existing code. This means that good code breeds good code and, unfortunately, the same is true about bad code.

These are my priorities when writing code:

1. It should work correctly.
2. It should be clean and readable.
3. ...
4. If needed, optimize for performance.

Lets start this with my favorite coding guideline: Write readable code instead of comments.