I love to write about my packages. Why? The code you type you know, you know the name of variables, you know how to interface looks, you know the architecture. It's like raising your own child and knowing his favorite ice-cream...
The fun comes, when your neighbor needs to run to the hospital to visit his dying father and he drops you his daughter at your door. You're a good man, so you say you look after her. It getting late so you want to make some dinner.
But what does she like? Can she eat spicy food or sweets? Is she allergic to something? Many questions you wished you asked your neighbor now, but that didn't come to your mind before, because you know by heart these things about your child.
Luckily for us, a code is a bit different - when it eats something different than it supposed to do, the worst thing that can happen is an exception or invalid input type. We don't think about other peoples' code much - compared to ours. It's either not tested, crap, legacy or full of static (pick your own favorite label for the code you read and that is not yours).
If you learn how to think like somebody you're not, you get into beginners mind. It might save a life of a child and also - in your case - you'll be able to write code not only you but also other people understand.
You'll get many benefits over your peers, just to name a few:
How do put there?
composer require your-package/name, a plugin with bundle or extension and run. You probably have done this dozen of times. Do you think this will give you nothing new? On contrary - you might be surprised, how hard to configure your package is.
Ask a good friend who you're patient with to use your package personally right in front of you. Make task simple, e.g.
They will probably follow steps in
README... oh, I've learned almost nobody reads them in these tests. They just find
composer require your-package/name and wait for the first exception before going to any README at all. Not really intentionally :)
In your eyes it might look like this:
I'm always tempted to give them clues - "click there, it's not exclude, it's excluded", but that would ruin your feedback. Stop any verbal and non-verbal output = shut up and listen.
Friend testing is really the best way to get feedback. You can read more about this process in short book Rocket Surgery Made Easy by my favorite common sense author Steve Krug.
On the other hand, it is consuming and you have to have many friends that are both willing to use your package and are feeling comfortable in failing to even run it.
Isn't there something you can do just by yourself that would keep their shoes on you? Something where all you need is yourself and free time and the only judge in your head? No, I don't mean masturbation.
It helps me shift my thinking from fast to slow one. It's very rare in programming because thanks to IDE we barely type in words:
<p>This code took 10 seconds and exactly 34 keystrokes to type. It's <strong>233 chars long</strong>.</p>
When we're in the flow and have clear idea what we code, most of our programming works looks like this.
Btw, if missed Social Psychology 101 on the university, Thinking, Fast and Slow covers 90 % of it. Be careful, after reading it you'll see how lazy human brains is by design - in politics, in coding even or your family.
"Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code. ...[Therefore,] making it easy to read makes it easier to write."
<footer class="blockquote-footer">Robert C. Martin, <cite>author of Clean Code</cite></footer>
...and we don't talk about open source here, where the ratio might be way over 1000 views per year even in small packages.
It will take around 2-5 minutes to write such text and it will be over 500 chars long.
That's slow thinking - with patience to detail, understanding in context and most importantly - critical thinking:
Writing such text - in private, for your colleagues or on your public blog - will give you many hints what you can do better with the code.
One example for all - after writing of my last 2 posts - 11 Steps to Migrate From Sculpin to Statie and 9 Steps to Migrate From Jekyll to Statie I realized, it's really difficult to switch from one static website to another. You need to follow many steps, in the correct order:
This got me to slow thinking:
I didn't think about this until I started writing the text. I assumed the post will give reader X points to follow. He or she will follow it, finish it and everybody is happy.
So I continued:
The hypothesis was made. Now only I only had to make a prototype. I did it over the weekend and used it to migrate blog of my friend and great mentor not only for PHPStorm - Tomáš Fejfar. It works and it was fun to explore static migration rules and limits. I learned a lot.
But this post is not about Statie. It's about how text about your code can give you ideas you never knew were there. Ideas that are awesome and push you further to create better and shorter code, that more people understand.
Give your code a text try and you'll see how deep the rabbit hole goes.
Do you learn from my contents or use open-souce packages like Rector every day?
Consider supporting it on GitHub Sponsors. I'd really appreciate it!