I don’t know about you but the older I get, the more things become similar. And I don’t mean it in a way “I’ve seen enough so nothing surprises me anymore”, but “I think I’ve seen it before… apparently a lot of approaches are really universal”. This time let’s approach similarity of writing good code and good article.
Why do you read code?
Usually you want to learn something. “Learn” sounds positive, but sometimes you just need some information and this damn code is not readable at all! At work, you usually want to understand what this code does and what his author had in mind. Your goal is to retrieve information.
Certainly, you might read code to learn some new approach, how to structure the code, how to use API etc. This is not the topic I’m touching here, but yet in this context might be interesting as well.
Why do you read article?
The main difference is that you might read article for fun. The author is funny, has great sense of humour and you feel like watching good movie - not much content, but very enjoyable. That’s awesome, but also that’s not something I want to talk about.
The context I want here is pragmatic approach - you read article, because you need to learn something. Learn about another culture, learn how to fix the bug, learn how to program more stuff.
Be polite
I love the response that Uncle Bob gave to talk by Christin Gorman: Github gist. Yep, that was inspiration for this article, but it became much clearer to me when I actually started writing articles here for the blog. I was thinking:
“If I were to visit my own article, how would I want it to look like?”
This is very subjective. Sometimes I believe that one should be as pragmatic as possible and sometimes - that some story around the topic is very handy. Some articles might just give you straightforward information how to solve concrete problem and some are simply interesting to read (hopefully). But the main goal of this blog is to give pragmatic information in clear and concise way.
Getting back to Uncle Bob, the most important part is:
Polite code is like a well written newspaper article. It allows you to bail out early. A well written article has a headline, a synopsis, and a set of paragraphs that begin with the high level concepts and get more and more detailed as you read through the article. At any point you can decide: “I get it! I don’t need to read further.” Indeed, this is how most people read newspapers or magazines. The articles are polite, because they allow you to get out quickly.
Be polite in code
You see, this code:
does exactly the same as below:
If reader is interested only in view dealing with emails, they don’t need to read 4 lines. It’s enough to read one line and second one gives them precise way to chunk of code that they’re really interested in. This is being polite.
This is like looking for some specific information in a book and not having table of contents. Can you imagine that? Nobody wants to go through whole book to find one piece of information. And nobody wants to go through whole 100-line method to find one piece of information. This is being polite, this is treating others as you would like to be treated on your own.
Be polite in articles
That’s why I often do “TL;DR” section in my articles about particular problems. If you Google this problem and find out this article, I want to help you as quickly as possible - because often I’d expect the same.
Sometimes I want to really understand the problem and which steps lead to the solution. Curiosity is awesome and I don’t want to discourage anyone from reading whole blog post. But even then, you might already know the problem very well and you want to skip introduction. Fair enough, let’s make it clear when problem description ends.
Or maybe you’ve read the whole article but then something clicked in your head and you need to get back to that part which now makes much more sense.
With sections all of the above is much easier to do than with poorly (or not) structured article.
Be polite everywhere (or TL;DR)
Please think what you would like to see when you open new java file or new article. Would you like to see one big method with 100 lines of code or one big blob of 100 lines of text? Probably not, so let’s make it right.
If you are looking for one specific information you probably don’t want to read the whole article. Solution? Let’s split our code and our articles into sections! More importantly, let’s make information in articles easier to find - which means much more than just doing “sections”. And let’s find out more ways that article and code are similar so we can make both a bit better.