One area I've been looking to improve in is understanding a codebase with no other information than the documentation.
I want to highlight a few key pieces of information:
You have no prior knowledge of this API or system.
There are no or very few YouTube tutorials, books, or other resources.
Typically when I am reaching to learn an API, it's because I want to accomplish a specific task with that API. Let's take a look at a project using Binary Ninja's Python API as an example:
api.binary.ninja/binaryninja.binaryview-module.ht…
Let's say we want to write a python script which iterates through some given binary file (let's say x86-64 architecture) and looks for 3 "add" x86-64 assembly instructions followed by a "jmp" instruction, anywhere in code sections of the binary file. This is an example "objective" that we could use in a situation where we need to utilize this new API.
My question is, given this API doc and these requirements, how would you approach utilizing only the documentation to solve this problem? I have some ideas of my own, but I want to hear each of your processes because I might learn something new that will help me become more efficient at utilizing docs.
The biggest issue I have is that docs document functionality only and not how to piece together functionality to solve a given problem... Whereas tutorials tend to piece together pieces in context to solve a given problem but they lack code-coverage, meaning they may only demo 5 methods of an entire API whereas the docs will show how to use nearly all methods.
Todd,
I think, it is still possible to follow the API Docs to understand the Intention behind a Code-base which Supports a Library or a Framework. In (most of the) normal cases, I would try to start with a Getting Started kind of kick-start and then gradually improve my Hello World Kick-Start by reading and applying the API understanding.
However with the constraints you have mentioned, the objective may fail if the API docs frustrates me at the beginning. If the API doc is comprehensive enough like the one I follow here, it is fine to look into those to learn and apply characteristics like,
Here comes my dramatic quote,
If Code is the Manuscript of a play or movie, API documentation should be the screen play and the demonstration that a Director would give to their actors.
In that case, it shouldn't be that hard to understand it entirely, I believe. Another great example of awesome API doc would be Node.js API doc.
Btw, the API doc example I gave first, I have been following just that to build some cool stuff on top of simple use-cases with a mobile app.
Long story short, My answer would be Depends!
Actually, I think the answer is within your question, you already say that:
As Tapas Adhikary has mentioned, you would go to source code itself and try to understand the intention. However, this approach conflicts with your "no prior knowledge" statement. For you to understand a codebase, you should know design patterns and you said you do not know that. Well, to tackle this problem with logic, you would simply refer to a mentor, a senior and ask them to explain how to utilize the codebase.
However, before doing that, you should have asked yourself another question: Do you really want to use that source in your project? I mean:
There should be standards to use an open source project in your software development team. You should refer to your seniors but below are convenient to judge a project:
Convenient Ways to Review Open Source Projects 101
Requirement Levels
Level 1: Minimal Requirements
Level 2: Optimal Requirements
Level 3: Maximal Requirements
A Case Study
A Level 3 Example
You do not suddenly say "let's use this" for every OS project you will find on the internet. You should review them and judge them. For instance, let's look at Ionic.
There are introductory sections in the Ionic framework documentations. However, its repo does not provide a way that shows their builds or coverage, it only has badges that shows NPM versions. So, it is kind of friendly, but I will have trust issues about how it functions. On the other hand, on their main page, I see many referrals, which means it is battle tested in the industry somewhere, which makes my worries about its build process fade away a little.
My Repo
So, I've been maintaining a project called
tgcli.You see many quick and automated badges about its builds, coverage, pypi version, which Python versions it supports, which license it has, how much it is downloaded by the real users in the last month and its coding style.
You visit its documentation and you see a "Getting Started" section, which contains information about how to install and use it, even to an extent that how to set it up in an environment. And the documentation is separated to sections.
Final Words
You need to review the project you are going to use. If you are in a desperate need of using it, like there's no alternative to it in the real world, then: