Why do we hate to read strangers Code?
This is one of the moments I recognize that I hate to read Code from other people! I don’t hate it, but I am often annoyed by the fact that I am getting annoyed by just reading another’s person code. And I assume, I am not the only one!

Let’s imagine the situation of a new project. You get a project that was coded by a stranger and the first time you look at it, it feels like “Oh well, that looks like total crap, I’ll throw it away and start from scratch!”. Previously I experienced a situation like the one I described above. I begun to think about the situation, and I think I know why this feeling is there and how I might be able to avoid it.
I am a PHP Developer, but the things I am describing are not related to any programming language. It is more like a general behavior of developers, no matter which programming language you prefer.
Documentation
Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing. — Dick Brandon
The thing about documentation is that we all hate it to write but we are all happy about that one little sentence that saved us a day of debugging. We don’t have to understand all the details when a piece of software is given to us, but we have to know the basis. For example, I was maintaining the website of my sister, which is well visited and made with WordPress. The Website was given to me like: “Hey, there are the credentials and can you make it faster, better, stronger, blah blah blah and the greatest website in the universe?”. I was like “sure.”. So at that time, I was not able to realize how painful the work would be. I started to dig in into the system, found a lot of useless Plugins and configurations. So I removed all the “crap,” started to check the website with several tools and moved the site to another “better” server. I turned out that some Plugins, that I removed were necessary for special processes and they didn’t work anymore.
If there were a documentation that just explains how things are made and WHY they are made the way they are made, that would be useful at the time I was operating. This is just one very personal example of how important the documentation is. At this time of the article, you might already remember some similar situations in your developer’s life.
I am playing with laravel for a while, and I love some approaches they make. Regarding the documentation thing, I love Taylor Otwell’s way to make sure, every developer who reads his class will know what is going on! Have you ever seen a comment like that in a code before:
/*
| — — — — — — — — — — — — — — — — — — — — — — — — — — — — — —
| Default Cache Store
| — — — — — — — — — — — — — — — — — — — — — — — — — — — — — —
| This option controls the default cache connection that gets used
| while
| using this caching library. This connection is used when another
| is
| not explicitly specified when executing a given caching function.
|
| Supported: “apc”, “array”, “database”, “file”, “memcached”,
| “redis”
|
*/ There you go. This Codeblock is as simple as a “hello world” but it is so powerful. There are just 3 Lines of text describing a specific value in a configuration file. Each of the lines is shorter than the one before. There is also a list of supported values, so you don’t have to google it.
This is just an example! It doesn’t have to be like this because this kind of documentation is rare and unusual but on the other side the most powerful documentation I’ve ever seen.
What do I mean with powerful? Have you ever tried to use a Framework offline? Just by jumping around in the different classes? Try it, and you will experience a complete new viewport.
What else?
So is documentation the only thing we are missing when we read strangers code? Nope, in my opinion, we all have a special understanding of a good app. Some of us know the 12 factors of an application. Some do not!
12 Factor Application
In the modern era, software is commonly delivered as a service: called web apps, or software-as-a-service. The twelve-factor app is a methodology for building software-as-a-service apps that…
The 12 Factor App methodology describes several aspects of an application that is made by following a “modern” standard. Whatever that might be! The 12 Factor App ist just an example for a reference. When you are building software, and you have a methodology like the 12-factor app in your head, why don’t you give a little hint for those who might don’t know that? Hint by hint, every junior developer will understand what you are going to archive with this app. They can start to guess what functionality might is and what it will do.
Conclusion
Documentation is a big advantage if it is done right. This little article does not describe every aspect of why we hate it to read others code, but it might help to understand how we can help others to write code that we love to read.
Try to answer the following questions regarding the documentation of you own app. If you can answer them, good. If the answers are in your documentation, excellent! If the material is at the place a developer would expect, you’re god! ;)
What is this Repository about?
What is the TechStack of this Repo?
How do I install the App?
How do I deploy the App?
What are the specials in this App? E.g., Why is this Website build with WordPress except for GravCMS?
How is the folder Structure and how do I make changes without crashing the system?
Is there something I need to know before I start developing new stuff for this particular app?
