5 ms·
Ask HN: How do you learn new libraries without much documentation?
At work, I have been asked to build a couple of POC's on a new Angular based framework our company purchased.
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?
- chrisco255 6y agoIf there isn't good documentation, then you have to learn the library by studying the source code. I will sometimes create my own notes on libraries as I go through module by module. This is time-consuming to be sure, especially up front. You'll pay a high price today for better control and speed with using the library down the road. 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).
- angrais 6y ago1. Read the source code to understand which methods exist in each module, then document that somewhere myself if necessary. 2. Ensure your IDE has autocomplete so you can step through the suggestions when importing a module or calling a method.
- oweiler 6y agoBoring answer but your best bet will be reading the source code and document each module's external API.
- thinkingemote 6y agoLook at the library's tests. It's quicker and better for learning functionality than "just read the source code". If it's proprietary and closed and obfuscated then you need to familiarise yourself with reverse engineering toolsets.
- digilypse 6y agoSeconding this! Tests are a wonderful way to quickly discovering the properties of the codebase that the authors considered important.
- quanticle 6y agoThe corollary to this is, "If there aren't tests, start by writing some unit tests on your own that exercise the library's functionality."
- mercora 6y agomaybe its just me and my avoidance of unit testing but often when i tried this it appeared overly complex at setting things up for testing and the code you need is buried in between some dozens tests and their setup. I think its a good idea to look at them but more often then not i did not want to get through this and just tried to understand the code flow by reading the source.
- me_againnnnnn 6y agoBoggles my mind that somebody would buy a tool that would require familiarising themselves with reverse engineering tools. I mean how ridiculous a product is that ?
- pankajdoharey 6y agoTests, Comments and Source are the other form of documentation apart from the traditional docs.
- trulyrandom 6y agoThe other comments offer some good advice. If I'm really desperate, I'll search GitHub for projects that use the library to see how they use it.
- sealor 6y agoI use Learning Tests for such situations. https://blog.thecodewhisperer.com/permalink/when-to-write-learning-tests https://blog.thecodewhisperer.com/permalink/when-to-write-le... (not fully read by me but seem to explain this technique very well)
- ChrisMarshallNY 6y agoOne of the tricks I use, is to write a minimal harness, then inject stimulus, and observe the response. 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.
- alxlaz 6y agoOh boy. I still have nightmares about this. At $former_workplace we had an entire SDK, a few hundred thousand LoCs in total, with basically no documentation whatsoever. The team that wrote most of it had long been laid off. We traded notes on how to do various things but as soon as you went out of whatever module you'd been typically working on, all bets were off. 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.
- sillysaurusx 6y ago1. learn a good editor. 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 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.
- izacus 6y agoThis sounds like trying to create a poor man's IDE with go to definition / find usages functionality. Is there an IntelliJ product for JS yet?
- quanticle 6y agoI haven't used it, but there is WebStorm [1]. Visual Studio Code also also has fairly good jump to definition/find usages, thanks to the fact that it has a typescript compiler built in, which allows it to perform analysis of JavaScript projects as well. [1]: https://www.jetbrains.com/webstorm/ https://www.jetbrains.com/webstorm/
- sillysaurusx 6y agoI regularly read and understand 50,000+ line codebases with this technique. Again, I suggest trying it before dismissing the idea. A good IDE is nice, when they work, but this fallback has worked 100% of the time. 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.
- deleted 6y ago[deleted]
- quanticle 6y agoIf you have the source code to this library, `find` and `grep` are your best friends. If nothing else, you should be able to find other usages of the code you're looking to use (or maybe even tests), which will let you know how that code is supposed to be used. The other things to look for are classes, functions, or modules that aren't used by other code in the library. Those tend to be the "top-level" code intended to be called by application code. Seeing how those are structured and what functionality they expose can be a great way to discover functionality that documentation leaves out.
- loosescrews 6y agoThere is lots of good advice about how to figure out how it works in this thread. 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.
- mytailorisrich 6y agoIf you think that this knowledge will be important to your employer then try not to share it too much in an organised and documented way but rather help others on specific issues. This is more effective to establish yourself as the expert and go to person. If you write a comprehensive documentation they others need you less.
- TimD1 6y agoYikes. Would you want to work in an environment where all your coworkers acted like this? Your suggestion may be necessary in a cut-throat workplace, but I'd be more inclined to GTFO and work somewhere that my team members actually try to help each other, instead of always acting in their own self interest.
- mytailorisrich 6y agoDid I suggest not to help? No, on the contrary. Of course you should be helpful, but you should also be smart. You want to be seen as valuable AND as difficult to replace. Help your employer succeed and help yourself succeed at the same time. What would you rather hear in management meetings? "We can't let Bob go, he's the expert on X, everyone goes to him for help and we need him" or "Sure Bob is an expert on X, but he wrote down all he knew so we'll manage". See, it's not about not helping, it's about helping while building and retaining leverage. That's why companies want to encourage "knowledge sharing". It's not to foster a friendly atmosphere, it's to be robust against someone leaving and to prevent someone from having too much leverage. Most experienced engineers know that and tend to be wary when asked to document what they know in details and/or to train others. As to act in one's own self interest, well sorry to be the one to break it to you, but that's how the world works in general and that is especially how the workplace works. And in fact that's how everyone works when there's a choice to be made. The sooner you realise that the better off you will be.
- emmanueloga_ 6y agoA good navigation tool can really help sort out a foreign code base. I suspect it could take you a few hours (with luck...) to install Sourcegraph but when you succeed it will be worth your time! (and the data should be local to the host where you install it). 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-sourcegraph-with-docker/ https://www.techrepublic.com/article/how-to-install-sourcegr...
- ekianjo 6y agoMore often than not, look at the code directly in case there's other way. Sometimes there are comments in the code that point to better understanding, if you are lucky.
- xadoc 6y agoIf the code has tests, I would start by looking at those tests. 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/ 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-Feathers/dp/0131177052 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.
- EliRivers 6y agoXadoc's advice above is good; unit tests. I work with poorly documented protocols that have been implemented "around the theme of the protocol" by hardware from a variety of suppliers, and this is how we work out its quirks. 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.
- mytailorisrich 6y agoThese are exploratory tests rather than unit tests, but your point stands.
- angrygoat 6y agoxadoc's last point is really important. The missing documentation is clearly impacting your productivity: you absolutely should raise this as in issue with more senior devs or management. There are a number of ways to respond, and they should be pleased that you have flagged the issue early.
- lawik 6y agoWhen I've been using open source libraries without significant docs I've mostly benefitted from actually reading the code. Assuming you have the source. This can be incredibly varying in complexity. I've found a large Elixir codebase, as a functional paradigm easier to grasp compared to a single library in heavy OOP style in Python. Python not enforcing much structure and this particular library doing a lot of inheritance which complicates the state and modelling in my head a lot. So it varies a lot per code base and experience. But if you have the code, that's what I'd use.
- jrumbut 6y agoIf you can't learn by example, which is the inductive process and the one that I am most comfortable with and it sounds like you are too, you need to learn by deduction. 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?
- OmarShehata 6y agoThere's a lot of good advice in here about how to work around this situation but the best thing you can do here could just be: email this company and ask them. 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.
- mijoharas 6y agoOne thing I haven't seen people suggesting here yet is to use a repl! 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).
- z3t4 6y agoThe source is the documentation. So read the source code. If the source is not available or obfuscated make sure you charge per hour.
- eru 6y agoNot directly helpful for your case, but useful in general: 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.
- christophilus 6y agoA combination of intellisence, a repl, and reading the source.
- cameronbrown 6y ago- Ping people directly in that community. - 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.
- blickentwapft 6y agoJust read the libraries source code, examine the methods and see what they doZ
- jyriand 6y agoUsually I just look into source code. Use 'tree' command to see the folder structure and then pick a file that seems relevant. Then I go to the bottom of the file and work my way up (usually the main entry points are the bottom, depending on the language of course).
- PowerfulWizard 6y agoThis is what my priorities would be: 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.
- satvikpendem 6y agoI don't. If it doesn't have good docs, it's usually not worth using. I know for your situation you need to use that particular library, but if given the choice, the better documented one is usually better to use.
- alec_kendall 6y agoJust out of curiosity, what is the library you’re using?