Ask HN: How do you learn new libraries without much documentation?

#1

Post by vedant_shety » Sat, Jul 11, 2020, 8:49 AM UTC

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 ''

- 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?

Re: Ask HN: How do you learn new libraries without much documentation?

#2

Post by chrisco255 » Sat, Jul 11, 2020, 9:03 AM UTC

If 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).

Re: Ask HN: How do you learn new libraries without much documentation?

#3

Post by angrais » Sat, Jul 11, 2020, 9:03 AM UTC

1. 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.

Re: Ask HN: How do you learn new libraries without much documentation?

#4

Post by oweiler » Sat, Jul 11, 2020, 9:06 AM UTC

Boring answer but your best bet will be reading the source code and document each module's external API.

Re: Ask HN: How do you learn new libraries without much documentation?

#5

Post by thinkingemote » Sat, Jul 11, 2020, 9:08 AM UTC

Look 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.

Re: Ask HN: How do you learn new libraries without much documentation?

#6

Post by pankajdoharey » Sat, Jul 11, 2020, 9:12 AM UTC

Tests, Comments and Source are the other form of documentation apart from the traditional docs.

Re: Ask HN: How do you learn new libraries without much documentation?

#7

Post by trulyrandom » Sat, Jul 11, 2020, 9:17 AM UTC

The 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.

Re: Ask HN: How do you learn new libraries without much documentation?

#8

Post by sealor » Sat, Jul 11, 2020, 9:20 AM UTC

I use Learning Tests for such situations.

https://blog.thecodewhisperer.com/permalink/when-to-write-le... (not fully read by me but seem to explain this technique very well)

Re: Ask HN: How do you learn new libraries without much documentation?

#9

Post by ChrisMarshallNY » Sat, Jul 11, 2020, 9:22 AM UTC

One 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.

Re: Ask HN: How do you learn new libraries without much documentation?

#10

Post by alxlaz » Sat, Jul 11, 2020, 9:22 AM UTC

Oh 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.