Hacker News Reader

Comment by toastal | Hacker News Reader

Using Google less for privacy reasons aside (and you should too), I’ve found that as my career has progressed, I find myself way more often reading source code and the base documentation. Or in the case of JavaScript and CSS usually the W3 spec is the clearest source; not only is it straight from the horse’s mouth (more accurate), but it really isn’t overly technical with use cases and examples, and most importantly it displays the types of the inputs and outputs.

View on HN

This got me thinking:

I regularly read source. And one of my pet peeves with TypeScript is that I will click on a type and have to walk half a dozen types deep to understand what it is. Because the library has sensibly abstracted types to be DRY and whatnot.

What I want is a type flattener that I can point at a type and it basically links it all so I see a raw type in all its verbose but complete glory.

I still think this is a great appeal of Clojure(Script), you often work with the "flat" "just data" representations directly. From https://youtu.be/VSdnJDO-xdg?t=3000 (transcript: https://github.com/matthiasn/talk-transcripts/blob/master/Hi...):

    Example - HttpServletRequest
    
    getAsyncContext, getAttribute, getAttributeNames,
    getCharacterEncoding, getContentLength,
    getContentType, getDispatcherType, getInputStream,
    getLocalAddr, getLocale, getLocales, getLocalName,
    getLocalPort, getParameter, getParameterMap,
    getParameterNames, getParameterValues, getProtocol,
    getReader, getRealPath, getRemoteAddr, getRemoteHost,
    getRemotePort, getRequestDispatcher, getScheme,
    getServerName, getServerPort, getServletContext,
    isAsyncStarted, isAsyncSupported, isSecure,
    removeAttribute, setAttribute, setCharacterEncoding,
    startAsync, startAsync...
    getHeader, getHeaderNames, getHeaders, getIntHeader...

"How many maps?" Vs.

    In Clojure, Just Use Maps
    
    {:remote-addr "127.0.0.1",
     :scheme :http,
     :query-params {"somekey" "somevalue"},
     :form-params {},
     :request-method :get,
     :query-string "somekey=somevalue",
     :content-type nil,
     :uri "/foobaz",
     :server-name "localhost",
     :params {"somekey" "somevalue"},
     :headers
            {"accept-encoding" "gzip, deflate",
              "connection" "close",
              "user-agent" "Apache-HttpClient/4.1.2 (java 1.5)",
              "content-length" "0",
              "host" "localhost:8383"},
     :content-length 0,
     :server-port 8383,
     :character-encoding nil}

"In Clojure, we just use maps. This stuff came over a wire in HTTP, as text. How did we turn it into this [the Java]?"

This is almost exactly TypeScript’s worldview at the type level. It’s just structural types. The only difference is that it’s statically analyzable as a core feature.

JS is a little more complicated than that, but (sorry to tell you) so is ClojureScript, where a “map” can become a bunch of different actual data types through the course of a normal runtime.

In all cases, sending plain maps/pojos is nice but receiving them is fraught. Again TypeScript helps here by providing type guards where your parse/validation code can be statically analyzed.

Edit: and in terms of serialization, all of these languages struggle with fidelity loss. Clojure has EDN or Transit if you’re willing to incur one cost or another. But by default you’re sending out a smaller subset of types than your runtime is using, and receiving the same.

I'm guessing you mean it's similar to the map case?

Clojure/Script of course approaches validation and parsing using schema systems (malli or spec) that has its advantages compared to static type based approaches.

I mean TypeScript’s structural type system is effectively “just use maps”. With very few exceptions, any structurally equivalent type is substitutable for another.

> Clojure/Script of course approaches validation and parsing using schema systems (malli or spec) that has its advantages compared to static type based approaches.

So does TypeScript. It has to, because the type system doesn’t have a runtime. The benefit in TS is that you also get static analysis.

Can you point to some exemplar TS schema system(s) suitable for structured data parsing and validation? I've seen io-ts but it seems quite clunky in comparison, but maybe it's not representative.

Typescript is fundamentally bad for this because the type system does not exist at runtime. I’ve yet to find one I like so I just hand roll both typings and JSON schema. Particularly because I want the schema for other languages too.

Replying to myself - Zod seems a better TS side library for this.

Yes, I would have pointed to Zod. There are a lot of options in the space, but I think there’s still room for improvement.

My (vaporware, but I’ve built something similar before on top of io-ts) project would provide a similar API, but with base types built from JSON Schema definitions, and automatically generate docs.

There are also opportunities to significantly improve runtime performance (at the expense of build time) by avoiding unnecessary parsing where statically checked code paths are already valid, eg naive multiple parse steps.

This will never cease to produce laughter in me :)

I want a type flattener and function call tree flattener for C++ and Rust, since I use those languages more than JS. Right now I make do by flattening call trees myself in Google Docs, but that's time-consuming.

You can use a merge type (on mobile so this may be wrong, but hopefully gets you on your way to where you’re going):

    type Merge<T> = { [K in keyof T]: T[K] }

Typical usage is with intersection types like:

    Merge<A & B>

Where the resulting type is not aliased, at least at the top level, and you just see the structure of both A and B. But it should also work for inheritance, interface extensions, and object type overloads.

I think as of either 4.4 or 4.5 you can also safely make it recursive.

I'm a TS dev and only switched in the last month from decades of Eclipse to VS Code. "Peek call hierarchy" is my favorite feature. Granted it doesn't totally flatten an inheritance chain but it saves a ton of time versus going one by one through references.

Depends on the source code and docs. Some projects have great docs, others have almost none and the learning process verges on “oral tradition”

I think the idea is that, as you get good at spelunking through source code, it becomes faster to find the answer in the source than to do anything else. E.g. I was wondering how division worked in Java, and right after searching for "ArithmeticException" in openjdk I ended up looking at HotSpot's implementation of div. Turns out (based on a source code comment) that it's defined in the JVM spec, but how would I have known that?

Some codebases don't have source available, e.g. Windows, so there I guess one would use the docs.

I agree. With Javascript projects and frameworks, documentation can be extremely hit or miss in a way that I don't experience with other language like Python, Java, or Go.

I still use Google to search the documentation more easily. The Python docs are usually in the top three results if you search for "python typeddict" or whatever.

I always felt the official docs to be quite low in the rankings. For some reason python always has tons of tutorials for every possible situation, and those seem to bury the docs. Also the official docs are some too verbose and still don't have the detail I'm after.

Maybe my second point is the reason for the first.

I often end up getting results only applicable to python 2. I really dislike that they changed the language so much without ensuring backwards compatibility or changing the name.

Add "Python 3" (in quotes) to your google queries. In short time Google will figure it out and start sending you to Python 3 tutorials and docs.

In fact, I think that's the default now. Google may have associated you with Python 2, but I'm getting almost all Python 3 results for any search Python related.

You can also filter by time, but that's less useful because Python 2.7 pushed the end of life date so far back.

Unfortunately a while back Google deprecated the use of quotes to indicate a "must" constraint. But it does still help somewhat.

My biggest gripe about technology in general is getting used to how something works, and then, for no reason at all (apparently) it just gets changed.

Google does this because a team wants to make a name so they do a retool or redesign, it is a line item on a budget sheet and a metric for bonuses or whatever.

Users be damned.

I've taken to freezing certain servers and never updating them just to fight back against this. I'm tired of breaking changes every few weeks. I'm tired of learning where an option was hid in this update, only to have it moved in the next one, and the next.

As an industry, shame should be wielded to prevent this. Microsoft was never held accountable for their transgressions with excel and Word. It really opened the gates for every other development house to do the same thing, and now, a decade and a half later...

Yup! For some reason I can more easily understand raw documentation and API spec. When I first started it felt more like gibberish

For me it's the exact opposite. Documentation - especially auto-generated one - immediately makes me feel lost. I don't know where to start and when I just read it by itself my brain shuts off within minutes. The only way I can use documentation is by using it as reference alongside a project I'm working on, that's why examples are one of the most important factors for me.

But I also have to say - better no examples than misleading, outdated ones. And please for dog's sake don't link to a site that requires registering an account to read nothing more than "further example" code snippets that turn out to be the same outdated examples with different variable names.

Right but I used to feel the same way. After years of programming, raw api spec and documentation started making sense. And I found that the answers I needed were more often than not in there

I've been gravitating toward Sourcegraph a lot more in leu of documentation. You really can't do much better than finding real life examples of how some library is used.

> I find myself way more often reading source code and the base documentation.

Yes, search engine results are for amateurs (except for finding the source, spec, base documentation, etc.). If you are serious, hold yourself and your learning to higher standards.

It's also faster to read the serious sources: They are much more dense and complete, requiring less searching around and accumulation of stuff, much more to the point, more authoritative and accurate, and IME more clear (I think because clear writing requires deep understanding and clear thinking, which is much more likely to be had by the dev who wrote the code or the experts writing the spec, than blogs, reddit, or even HN commenters).

You'll find that most of the online forum/blog authors don't actually know what they are talking about (and that many of your peers have big holes or misunderstandings).

> Yes, search engine results are for amatuers...

I don't think that's accurate. Like the gp, I find myself relying more and more on reading the source and reading specs (WhatWG, RFCs, etc). However, search engine results are still incredibly valuable.

> Yes, search engine results are for amateurs (except for finding the source, spec, base documentation, etc.). If you are serious, hold yourself and your learning to higher standards.

This is exceptionally gatekeepy and predicated on the assumption that everyone learns or consumes knowledge in the same way you do, which is just not true. We already work in a profession that has issues with gatekeeping - I think we should avoid exacerbating that.

  > We already work in a profession that has issues with gatekeeping - I think we should avoid exacerbating that.

Why? Law and Medicine are gatekept fields, the minimum bar is essential for providing such sensitive services. With all the security issues - never mind accessibility - I think that professional software development should be gatekept.

Hobbist software development - where many of us started - should of course have welcoming arms to new members. I wonder how the Law and Medicine fields would cope with hobbist communities.

Reply on news.ycombinator.com