This is proprietary code for a niche industry so the community isn't as large. I also don't have access to any experts on this software.
- A common issue I face is when I want to import a module( and know that the functionality exists) but don't know what do I call and where can I call it from
eg: import { XYZ } from '<WHERE>'
- I have tried asking questions on their private community but it's pretty dead and no one ever responds
There are some tutorial courses but it's can only take you so far. How do I get better at this framework or at least good enough to build some basic POCs?
If it has no tests, then I would slowly try to build tests to document the functionality that I need. In your case being Angular that might be having simple html pages with the smallest module that you need.
How to find things? If you're on Windows try AstroGrep http://astrogrep.sourceforge.net/ to quickly search and jump around in the code or in any system I use VS Code for a similar functionality. Also learn to use command line find/grep.
The book "Working Effectively with Legacy Code" also helped me be more comfortable navigating and changing large code bases, in a long term view I recommend this book to every developer https://www.amazon.co.uk/Working-Effectively-Legacy-Michael-...
Lastly, I would raise this because the company might not be aware they are buying a low quality framework that maybe ticks all the boxes in the contract but is in effect impossible to use by their current developers (you), it might be there's other people with more experience in said niche that might be able to help. In the private community maybe some people would be able to accept a short contract to help train you.
A battery of unit tests, starting with the simplest functions it offers, and thence upwards into more complicated tests (i.e. chained calls of the presented functions) where we track what internal state we think the system should have at that point in the tests and interrogate it to discover what internal state it really does have.
I don't know much about Angular but I think most of these things are pretty much universal:
> A common issue I face is when I want to import a module( and know that the functionality exists) but don't know what do I call and where can I call it from
Generate call graphs from the source code. It's generally a good bet that the functions at (or near) the top of the call graphs are the ones that you're supposed to call.
If the library has automated tests, have a look at those -- it won't give you much information about idiomatic usage, but will at least tell you what parts of the whole thing you're supposed to interface with.
Liberally grep through the source code for whatever functionality you're looking for. In the absence of documentation, you'll have to create your own "mental map" of what things there are, and where.
Other than that, all I can do is recommend everyone else's generic advice: read the source code, take lots of notes.
As you iterate through each module in the source code, ask yourself what each function or class does, what its purpose is, whether there are any side effects or what sort of state changes occur when a method is called (if any).
If it's proprietary and closed and obfuscated then you need to familiarise yourself with reverse engineering toolsets.
2. write a script to concatenate all the code files in a folder, separated by filenames.
3. pipe that result to your editor.
4. use your editor's "find" functionality.
By reading the entire source code in a single file, you have global knowledge of the entire codebase. All the information is available to you. I suggest you try it before dismissing the idea, as I once did.
https://github.com/shawwn/scrap is what I use. `codefiles | grep js$ | xargs merge | ft js` will open all javascript codefiles in vim, in JS mode. `cppfiles | xargs merge | ft cpp` will open all C++ files in vim, in C++ mode.
Free yourself from the loop of asking other people for answers. Stop that. Read code.
If you limit yourself to "projects that have good documentation," you'll miss out on 90% of the interesting code in the world.
Reading all the code might be a decent approach for small libraries but sometimes it's excessive.
It's remarkable how offensive this idea is to people. It's not like I came up with the idea this morning. I've been reading hundred-thousand line codebases for many, many years this way. It's how I studied and understood the original bitcoin codebase.
But, you know, if you really want to be stuck in the loop of "ok, this file calls Foo, let me switch to terminal and search for Foo... Ok, now I'll open that file and read it.. Oh it calls Bar, I'll search for bar..." then feel free.
And yeah, an IDE is the antidote. If it's a JS project, use `webstorm .`. For python, use `charm .` Unfortunately `clion .` doesn't seem to work for C++ codebases -- you have to "import" the code first, which is highly annoying and generates extra CMakeList.txt flies. VSCode might be fine and automatic and perfect go-to-definition functionality even for template metaprogramming; I don't know.
But I do know that the technique I've described above will work 100% of the time.
Is there an IntelliJ product for JS yet?
CLion is for C++. PyCharm is for Python. Webstorm is for JS. But Vim is for everything.
To put it differently: how often do you use ripgrep on a large codebase? If the answer is "often," then every time you switch to your terminal, you're losing context about the code. No wonder it's impossible to understand when you're having to read code fragments every few minutes. Read the whole code.
One piece of advice I have is write formal documentation of some form as you figure it out. Share it as widely as possible. If nothing else, it will be very useful for you and your co-workers in the future. It sounds like there is some sort of community you can share it with. Ideally there would be some way to contribute it back the to source of the software for distribution with it, but that often isn't possible with proprietary software.
Regardless of who you share it with, it will help establish you as an expert within that group. In addition to helping people, it will likely be good for your career.
Import the thing, and then look at what it provides. If something seems useful, try calling the function/instantiating the class, if it gives you an error message, try with different arguments.
Hopefully, you should have some idea of what the library is trying to do, so you should be able to see some functions that look like they accomplish the kinds of things you want. Guess what kinds of arguments they take and try it. If you can't figure that out, jump into the source and figure it out.
I find it's much nicer working interactively like this than just reading the source because you can immediately try things out rather than jumping back and forth all the time.
Also, some languages like python have a `help()` function that you can call with any class/method/function to get to the docs on it (I can't remember anything like that for javascript, so you might be out of luck there).
- Get yourself a notebook (or Google doc, whatever) and thoroughly write down everything you learn.
- Walk through the source code methodically, and read the jsdoc/function names wherever possible. Don't read too much into implementation.
- Use whatever tools your comfortable for this. Generating call graphs or reading through tests first make a lot more sense than trying to read the entire library.
- Start by documenting Hello World and go from there.
1. Make sure you have a good debugger set up for any existing code. This is to answer the question of exactly how a function behaves, what are the meaning of parameters, etc. You know you're going to be dealing with undocumented functionality, so you need a way to quickly answer your own questions.
2. Someone at your organization is paying for this right? Ask them to pressure the supplier for one-on-one support to answer your questions regarding how to use it. You want someone on a video conference who knows what they're talking about so you're can explain things quickly and not have to write up detailed emails and wait for response.
3. You could try to document it yourself: Locate all the exports and create a list of them. Browse it for key names and concepts. Write down the purpose of each, and their relationships. There might be a lot of these items but it won't be infinite. Even if there are 500, if you do 20 a day you'll be done in 6 weeks and by that time you should have a pretty good picture of what's going on.
https://blog.thecodewhisperer.com/permalink/when-to-write-le... (not fully read by me but seem to explain this technique very well)
If you are paying for this proprietary software, especially if you're still in the "evaluating whether we should spend a lot of money on this" phase, you should absolutely push back on them. Ask them all the questions you need, big or small. It's really on them to give you something well documented, and if they don't, they better be willing to answer all your questions about it.
I've seen this sort of customer behavior be the catalyst to get companies to actually document their stuff because all their engineers time was spent answering the same questions over and over.
For node or Ruby or other pure open source environments there are endless examples on the Internet and when you want to learn you can read 50 of them until they start making sense. When there isn't much documentation, you have to deduce the reasoning that went into the codebase or you may never make progress. It's a slower and more demanding process.
On a side note, before the explosion of web content, this was how a lot of programming had to be learned. Maybe talk to/bring in older programmers to help you?
Found a random article online that shows step by step with pictures [1] (I think is a bit more visual than the canonical docs).
Good luck!
1: https://www.techrepublic.com/article/how-to-install-sourcegr...
I do this for Bluetooth devices, and I have also used utilities, like REST explorer apps, Bluetooth Explorer, PacketLogger, USB Explorer, Charles Proxy and Wireshark.
The drawback is, that I could accidentally codify features subject to change.
All that said, I tend to be veeery leery of any dependency. Adding dependencies is a serious issue.
If the dependency is badly documented, then that’s a “red flag” that it may not have much of a future.
In strongly statically typed languages like Haskell, the types can often give you an adequate introduction into a new library.
There's quite a few open source Haskell libraries that basically only have type annotations, but no proper documentation. The latter would be better, but the former is already surprisingly useful on its own.
2. Ensure your IDE has autocomplete so you can step through the suggestions when importing a module or calling a method.
