1000: Use Search-oriented Programming
The idea of search-oriented programming is based on two premises:
- Every useful class, method, or attribute has been used at least once. If nobody is using it, do not use it either.
- Every line in mature software has been checked by multiple people. Therefore every class, method, or variable has a descriptive and understandable name.
Search In Existing Code
If you know the name of the class or function you can try to google it. You will get most likely just a package page, documentation, or Stackoverflow questions. This is a good start but you can get better results if you use more specialized search engines. Specific examples will help you to learn not only about the entity itself but also about other entities that are used nearby.
Where To Search
- Search in your project. It is just one keyboard shortcut away and it is the best code that you can find. It has passed code review, you can find relevant pull requests, or even talk with people who have written that code. Many IDE allows you to easily find all usages of the entity.
- Search in repositories of your organization. It could take a little bit longer and you may not be able to talk with the others of that code. On the other side, there is a greater chance that you will find something.
- Search in communication in your company. If you have problems with figuring out how it should be used, you are for sure not the first one. Try to search in wikis, Slack, e-mails, etc.
- Search in the source code of that project. If it is a public method, then it should be covered at least with unit tests. By finding these tests, you can learn what was the intended usage by the authors.
- Search in open source repositories. GitHub allows you to search in their 100M+ repositories. So you will find for sure many good examples. If you compare search GitHub results with initial Google results you can that it is much more useful.
Another advantage of using GitHub is that you not only find the function itself and its friends, but you will also find how it is used in tests. Documentation of how to use
requests.Session is short, but since it is a lot, you will find many examples.
Since the code was written by sane people and reviewed by other people, there is a very high chance that used names would be descriptive. Therefore you can always try to search for possible class or method names to see if anything useful is there.
If you are searching for code related to login workflow, you can try to search for string
login. If you want to find code related to manipulation with items in a shopping cart, you can search for words like
|0011: Make Small Steps||Keep Methods Small Than Your Head: 1001|