Comment by alex_smart | Hacker News Reader

Comment by alex_smart | Hacker News Reader

Parent Full thread

Almost all programming tutorials and even books to a certain extent suffer with the problem of terrible examples. Properly motivating most design patterns requires context of a sufficiently complex codebase that tutorials and books simply do not have the space of getting into. This particular case is especially bad, probably because they had the goal of having the whole article fit in one page. ("You can download a printer-friendly version to display in your office.")

> There is no guidance whatsoever (ie: Martin Fowler's Rule of Three).

That is completely unfair imo. Although not properly motivated, the advice is all there. "When designing abstractions, do not prematurely couple behaviors that may evolve separately in the longer term." "When in doubt, keep behaviors separate until enough common patterns emerge over time that justify the coupling."

Simplified maxims like "Rule of Three" do more harm than good. Don't couple unrelated concerns is a much higher programming virtue than DRY.

> Properly motivating most design patterns requires context of a sufficiently complex codebase

As someone that's made a best selling technical course, I strongly disagree.

It's 100% laziness and/or disregard for the reader.

The reason examples are as bad as they are is that people rush to get something published rather than put themselves in the audience's position and make sure it's concise and makes sense.

It's not like webpage space is expensive. There's plenty of room to walk through a good example, it just requires a little effort.

What does sales have to do with what you're claiming? Please share the course and or examples of it being done well without requiring that excessive context, so that there's something to support your claim.

Well if my course and teaching was crap I wouldn't get good reviews and therefore many sales. I've spent $0 on marketing.

https://www.udemy.com/neo4j-foundations/

There are many people who do teach and explain topics well. Richard Feynman comes to mind.

I've found Abdul Bari on YouTube to also be an excellent teacher around technical topics.

Not related to the topic at hand, but who buys these courses? Going off the chapter titles it looks like it’s all basic ‘read the documentation’ kind of stuff (to me). I could imagine it being useful to beginners, but not anyone with a moderate amount of experience (they’d just go to the Neo4j documentation).

On the other hand, what beginner starts with Neo4j and Cypher? Is there really enough of them to justify a whole course? Apparently there are, it just feels weird to me.

You're right in that if you go through the docs you can find all the info you might need.

It's really catered for beginners, people that have next to no knowledge of graph databases or Neo4j and want to get up to speed in just a few hours.

I imagine some people may not even be super technical, but may want to learn just the basics of querying a DB at work to get some basic info out of it.

Apart from lessons there are also exercises for people to practice what they just learnt, and I do my best to point out gotchas and keep it mildly entertaining with a gentle progression in difficulty.

>It's not like webpage space is expensive.

It is not the webpage space. It is people's limited attention spans and ability to focus. A complex example is needed to properly motivate certain concepts, but too complex an example also contains too many other details that the reader gets bogged down/distracted from the main concept being discussed.

At least that is my hypothesis for why almost all programming books and tutorials have terrible examples. I am happy to be proven wrong.

Coming back to the article, I looked at some of the previous articles from the same series, and to me it feels like a very conscious decision to only include 3-4 line code examples.

> It's not like webpage space is expensive. There's plenty of room to walk through a good example, it just requires a little effort.

Right at the top of the page:

> A version of this post originally appeared in Google bathrooms worldwide as a Google Testing on the Toilet episode. You can download a printer-friendly version to display in your office.

So no, there isn't room for a longer example.

Reply on news.ycombinator.com