316 words — categories: notes
Some thoughts on programming from a non-programmer (at least by trade).
Beware of tools that are too recent. Sometimes change is good. Oftentimes it isn’t.
Developers like shiny new gadgets. These tend to be of lesser quality than older, more robust ones.
Whenever someone calls their library “simple” or “easy”, skip it. It’s likely to be a poorly documented, inconsistent, and wasteful solution to whatever problem you might have.
Often, ugly and functioning is way better than flashy and buggy.
No matter how many stars a repo has on GitHub, what’s more important is the number of issues (open and closed) it has collected.
Read a repo’s documentation (README or otherwise). If you don’t understand it, chances are the project is also unusable. If the author(s) can’t explain concisely how to use their work, skip it.
When you read a repo’s issues, pay attention to the type of question people have. If they’re about features, it may be a good sign; the library works and people want more functionality. If most questions are about configuration or getting basic functionality to work, then skip the library altogether.
If the minimal examples don’t work, skip the library.
Official documentation that doesn’t reflect current functionality is one of the main reasons to skip a library. I was trying to use Sphinx. Their documentation contains a tutorial that’s years old, and so are the instructions. And that’s the quickstart of the application!
The value a tool can provide you with is not worth the time to make it work, if it’s broken or has unreliable documentation.
The official documentation of the most popular tools is orders of magnitude better than any anon’s hack on StackOverflow. Read it.
Learning an IDE can be wasted time, given the speed at which tools fall out of favor in the community. A good text editor like Vim and a terminal are all you need.