Most tutorials are not for non-developers, they’re for other developers who are also in the ecosystem. They’re more like academic papers (peer-to-peer communication of new discoveries) than they are like a pop sci book or show meant for a general audience.
And that’s okay! Great even! As a fellow peer I benefit greatly from those tutorials. Sometimes even from my own notes published and forgotten years ago.
This is why courses and other structured learning materials exist. Beginners have to be nurtured through lots of context that builds up slowly. If every article had to start from scratch, we’d never get to anything interesting. By the time we got to the interesting bit after 30,000 words of preamble, you’d be long gone as a reader.
And the very next reader would complain that the 30,000 words were not enough introduction to the topic. They needed 40,000.
> Beginners have to be nurtured through lots of context that builds up slowly.
My son is 17 and very interested in programming. Had to explain to him public, private, internal, and also static the other night.
I then joked, you should ask your teacher about recursion tomorrow. He's with his mom this weekend, but I'm anxiously awaiting hearing how that went.
Ah, the infamous public static void main(String[] args). Hopefully the next generation won’t need to learn all those concepts up front with the introduction of instance main methods in Java 25.
https://openjdk.org/jeps/512
I actually think the inscrutable Main method in java has some value. As a kid, I loved to know how things worked and always did things like read instruction manuals and read ahead in school textbooks. I wanted to know everything about anything, and I wanted to know how it worked from the bottom up.
The java main method taught me "This is abstraction, an important concept in programming. You won't always know how all the magic works all the time"
It taught that you have to deal with black boxes.
Also, I never saw it cause problems in CS101 classes, because the kids curious enough to want to know something their professor didn't explicitly talk about were usually the ones who would do fine at learning all the parts of it.
The kids who struggle with programming never seemed to have problems following "Just write your code here, you will learn more about it later"
He’s starting with Java? I wonder if that’s the right language to start with. What is he most interested in doing? Anyway thanks for nurturing the next generation.
I fully disagree with Java as a starting point and it was an interesting conversation with the teacher.
Apparently, "College Prep" courses more or less determine that Java is the language that they should use.
His teacher thought it was stupid as well, but sometimes your hands are tied. That's what the schools are using as a starting metric though.
He was apparently the only person in the class that said he wanted to do software engineering. Don't worry, he'll be a polyglot before he reaches college.
I learned Java in uni and think it's a fine language to start with. It's also been modernized a lot in the past decade, and if you really want a more modern language it's easy to transition to Kotlin.
I'd take Java over Python or JS any day. It wins on performance, it wins on type system, js is just a plain trash language not at all suited for general purpose programming (TS solves some problems but not all and it has its own problems) and python is fineish but it's slow and just kind of icky, I'd never do serious software development in python. It's fine for small scripts and notebooks and such, we learned python as part of our math classes while the programming classes focused primarily on Java. We also had a class on web development using JS, ML using Python and windows programming using C++ and C#.
I struggle to see any significantly better candidates for a first language than Java. Sure you could go with C but nobody really uses it any more outside of niches. C++ is out, too much stuff. I really like C#, it's my daily driver and I wouldn't mind it as a first language but I think Java is more approachable for beginners. Less confusing syntax to learn. I don't know Go but maybe that could be an alternative? Other than that I'm a bit out of options.
Java is a fairly simple language that's easy to learn and allows teaching a lot of important concepts that will be useful in other languages moving forward. That's a big thing I think, it's not meant to be the only language. The word polyglot is used some times, to me it just means programmer. I don't know any competent developers who only know one language. You end up learning multiple and I think Java is a good entry point.
C# is amazing. Decisions at the education level were made well before it went cross-platform though (FWIW, I've been using it since before v1.1).
Would be interesting in what confusing syntax you're referring to. I think one of the beauties of it is that it's additive. You can program plenty of simple stuff in it with conventional style code, but there's a lot of syntactic sugar available that makes things so easy when you need to start scaling things.
I agree, C# is my language of choice and I've been using it professionally for over 5 years. I use it for personal projects as well.
I'm referring to all the stuff C# has that Java doesn't. Async, ref/in/out keywords, extension methods, linq, lots of stuff. Maybe it's not a big deal, like I said I wouldn't really mind it. I just think Java is a bit simpler in this regard which is an advantage for beginners.
Some differences where I prefer java are checked exceptions and imports. C# usings are ambiguous, it can be difficult to figure out where things are coming from for code samples outside an IDE. And checked exceptions are just good IMO. I've never seen why people dislike them, having used Java and C# I think Java does it better. It's easy to miss exceptions in C#, I wish library developers could use checked exceptions to tell me which exceptions I should worry about.
Anyway both languages are great first languages and great general purpose languages. Highly recommend both.
Thanks for taking the time to respond. Ultimately though, most of those aren't required from the beginning, but the syntactic sugar, abstractions, and performance gains from them are amazing.
You probably already know, but I'll opine a little bit about extension methods. I use them a lot.
Entities > Repositories > Functionality. All split out.
- Entities (pretty much just gets and sets, nothing more than necessary).
- Repositories via extensions to determine where the data comes and goes from (some data comes from SQL, some from Redis, some from Postgres, doesn't matter since it's split out) and any particular queries you need for optimizing things.
- Functionality via more extensions without adding additional code to the entities.
Separation of purpose/use.
I may or may not have completely replaced our data layer in the middle of the height of our season with no interruption. Little bit passionate about this one.
Would you happen to have something like a github repo with examples of those repositories? I'd be interested in seeing that.
Personally I'm not a big fan of copious extensions. I use them some times but I'd describe my usage as sparingly.
I wish. It's on Github, but my hands are tied and I can't share them since it's someone else's property now (hooray for exits, I think).
It's mostly a thought process...
I have or need something (entity), lets get data about it (repository/extensions), we need to do something with this now (only extensions).
Lots of "static" and "this" involved, but the separation and eventual simplicity makes it worth the effort.
Edit: I tried going through some of them to anonymize some for examples, but it felt like treading in dangerous territory.
Java's a pretty good beginning programming language. Outside of the mystical incantation of `public static void main(String[] args) {` and what the difference between `new ArrayList` and `ArrayList.new()` is (I still don't know but I haven't really touched it since college), it's a good statically typed imperative language that you can throw objects and functional stuff into when it's time, isn't going to give you weird errors about indentation, has just enough pointers for you to learn how to avoid a `NullPointerException`, does things pretty "conventionally" (ie, there's not a lot in Java that doesn't also show up in other languages), and is easy to compile and run (when you're not using 3rd party libraries, which students in something like a Data Structures and Algorithms class aren't going to be using). Ideally you have another class teaching you another language too so you get the double bonus of learning what a language is and what a language isn't, and Python's good for that, but by itself Java's fine
> Outside of the mystical incantation of `public static void main(String[] args) {`
I don't think it's mystical. If you don't have an instance of the class yet, you need a starting point and static fills that void (lol. I'll show myself out)
My first programming class was Java. That was 8 years ago. Maybe the curriculum designers thought Java would be relevant for the workplace? The education system always lags several years behind industry trends.
My first programming was also Java. That was...27 years ago! That's some lag.
> 27 years ago!
Sometimes, I feel like I'm the only old guy on here. BASIC, VB6, .NET, and some Java along the way.
Too many new ones to list, although that might be a whole other problem in itself.
> Had to explain to him public, private, internal, and also static the other night.
Access modifiers are sort of a dying breed in a lot of places aren't they? We use Go, so we're obviously still using the two it comes with, but it's public vs module only and fairly intuitive. Every other language we have in production, doesn't make use of access modifiers. Similarily while static is a thing in Python, it's hard to see what advantages it brings compared to a free function if you're using a programming language that doesn't require you to have object instances to call non-static functions. Obviously access modifiers will stick around in a lot of organisations, but there will be plenty of jobs where you never have to work with them.
The way Go handles modules, is frankly one of the few language feature of any language I've ever worked with that I wish was in every language I work with. It's so easy to use and so hard to mess up. Ok, I guess it's not hard to mess it up, but it's not intuitive.
Access modifiers are useful, albeit not for beginners. They're most useful in statically typed languages with good tooling where they keep auto-generated API docs and autocompletions clean.
Static methods are useful for namespacing, e.g.
In some languages you can of course make a global free function called someThingFromString which does the same thing, but then (a) it won't have access to private methods so the public API surface gets more polluted with stuff the user maybe shouldn't call themselves, and (b) it won't show up in the right place in generated API docs and (c) it won't show up in the expected place in type autocompletion.Kotlin has both static methods (or rather companion objects which are an equivalent), and also top level free functions, and when writing it I find myself creating static methods a lot more often for the above reasons.
I probably shouldn't have worded it quite the way I did. Considering I praise Go's access modifiers. What I meant was the "old" way of having lots of them and explicitly having to write them out. I haven't tried Kotlin but it sounds nice.
What I like about Go is the simplicity. Everything inside a folder is a package/module and any method beginning with a capital letter is public while every method starting with a lowercase name is package/module only. Coming from a decade of C# it was such a nice thing.
I do work with a lot of Python where you don't have private methods. I mean, you can set up your corporate environment to "hide" _methods or whatever, but they are never turly private, and static methods are... well... they are basically just namedspaced top level functions.
Not going to disagree. It's the sandbox that we're playing in though (dealing with, HOORAY JAVA!) since it's a class at school.
Have to start somewhere, teach them better alternatives as they evolve. Not even going to broach the prototype-based programing stuff until he comfortably has the basics understood.
Edit: I don't GAF about downvotes, but I would at least expect a response about why. If you don't like the philosophy, give me some reasons. Don't like something else, tell me why. I'll happily debate anyone all day long
Maybe he and his teacher are caught in a loop ;)
I think Java is dying.
If you want to teach algorithmic thinking, teach Python.
If you want to teach hardware and low-level systems, teach C.
At the moment, I see this pattern for mega enterprise:
* C++ for scientific, mathematical, financial core libraries
* Java for heavyweight backend services that run on Linux
* DotNET for thick clients that run on Windows desktops/laptops
* NodeJS for lightweight backend services that run on Linux
* HTML/CSS/JavaScript (plus frameworkds) for lightweight web apps
* Python for data analysis and AI/ML work
Some notes:
.NET can serve the same use cases as Java, it's not just for windows programming. It's actually getting really good.
NodeJS does nothing better than anyone. The only things I can think of that make node worth using is electron and react native, maybe Next but I'd much rather do SSR in a real programming language personally. I would never use node as a pure backend, there's just no reason to and JS is an F tier language. TS brings it up to like C but it's still just not good enough to compete.
I can't see any reason to choose node for typical backend programming and such unless your devs only know JS. Any other language is probably better suited.
I agree with lots of things in your reply. In an enterprise setting where you mostly don't care about size of deployed application, then Electron is a godsend, where you can deploy a 500MB "Hello, World!" desktop app written in HTML/CSS/JS/TS in an afternoon. I know all about the bloat, but 99% of enterprise users don't care. A good web programmer can pump out very slick desktop apps incredibly quickly using Electron.
This is the primary explanation when I see NodeJS backends in enterprise. Mostly, those projects only have medium to low skill "web devs" (sorry, I cringe when I write that term).".NET can serve the same use cases as Java, it's not just for windows programming. It's actually getting really good."
Last time I tried NET was 15 years ago, so I have no first hand knowledge anymore, but I do read regular complaints, that cross compiling to Linux(or developing there) comes still with major hurdles at times?
Nah, DotNET is amazing these days. At the risk of starting a holy war, it is neck-and-neck with Java, and I say that as a Java fanboi. I think it is good to have healthy competition between languages (and ecosystems), like C++ and Rust (and a little bit Zig) or GCC and Clang or Java and DotNet or Python and Ruby or NodeJS and Deno. Plenty of people are compiling and deploying to Linux after DotNetCore went open source. Plus, you can use JetBrains Rider, which is a cross-platform IDE for C#, from the makers of IntelliJ.
.NET is amazing and keeps getting better. JetBrains is killing it with their IDEs and add-ons.
Currently running nearly a dozen different services written in .NET running on Alpine in K8S.
Started transitioning most of my code to .NET Core/Standard when they first came out. Sadly, I still have to deal with some ASP.NET MVC code that was written before and requires .NET Framework
I concur with most of your thoughts, except that Java is never going away. I might wish that it would, but here we are.
Java doesn't have an internal modifier. Concepts like public, private and static exist in Python too.
"Most tutorials are not for non-developers"
That has been repeated in the comments many times now, but the very headline says that this tutorial was indeed also intended for non developers.
Like some open source Github project that the author merely wanted to install, not starting to mess with the code. Basically, it is complaining in a satirical way about installation readmes, that maybe they could be made easier, that also non developers can follow some simple steps. A complaint that I can very much agree with, even though I am a developer. But so often little steps are left out and when that happens in a area you are not familiar with, then this can mean lots of wasted hours.
> "That has been repeated in the comments many times now, but the very headline says that this tutorial was indeed also intended for non developers"
tbf, that's not how I read the headline. The headline is: "How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner"
The author is a beginner, which puts them in the field - so the parent comment is valid no?
The headline has been edited, in its current shape I tend to agree to you.
> it is complaining in a satirical way about installation readmes, that maybe they could be made easier, that also non developers can follow some simple steps
See I missed that context :D
Installation readmes are an interesting example – they shouldn’t exist. Put that effort in an install script instead.
If you want me to mechanically follow some steps, perhaps with a decision tree attached … computers are really good at that!
The install script may not have all the context it needs to be installed. In the long run it is better to teach the user how your software works in plain english.
Even in projects with an install script, for example pmbootstrap, the install script also needs a tutorial.
In my experience, projects with minimal documentation and an install script will have the the install script fail halfway through because it assumed something about my system that isn't true, or it will do something incredibly insecure like requesting su and then curl | bash
Just because you have access to the text doesn't mean you're the intended audience.
Probably a good thing for us to all remember here on the interwebs where everything is accessible but written for no one
> Most tutorials are not for non-developers, they’re for other developers who are also in the ecosystem.
To me eye, most tutorial nowadays are so a developer can put "made public contribution to <X>" on their resume or quarterly evaluation rather than helping other developers.
I'd be even happier if the original writer would simply come back 3 months later and retrace their own directions. That would make the tutorial vastly better as they will suddenly see all the little things they left out.
Entirely 100% true. I can count on one hand the times I've said "wow, this documentation was written by someone who cared". Threejs is a good example here, but even then it is subject to API rot and needless reference chasing.
Examples are often the best way to do documentation, sadly.
I've been leaning on test suites more and more for this. It's almost like a test suite should contain comprehensive tutorials. You know the API is good (hopefully) because if it isn't, the CI/CD pipeline wouldn't have let the release through.
I guess I disagree that it's a good thing.
As a developer, I think most documentation is terrible both for developers and non-developers alike. And if you write your documentation so that it is useful to non-developers, it's still useful for developers.
There's no downside to writing accessible documentation, except that it requires a modicum of skill and effort. That's the real reason it's so rare, I think.
I also disagree that developer documentation is like academic papers. The ways they fail are almost opposite: academic papers are overly long and overwritten, because the authors want to be very careful and complete. Developer documentation is too short and hastily written, because they often don't care if it's helpful to anybody else.
The end result may be the same: neither are useful except to a small number of experts: the people who could probably do it themselves already, and thus may not even really need the write up to begin with. But that's a failure, not a feature to be celebrated.
> Beginners have to be nurtured through lots of context that builds up slowly.
I agree and when I write for such an audience, I try to be detailed and build on a proper story that they can follow through.
I do have a complaint about attempts to smoothen the DX which a lot of projects do that results in something which helps only the absolute beginner. Logs are not easily accessible or missing. It's not easy to cut/paste or grep for errors in things etc. Basically, many of of the familiar tools and techniques which people have used to find their way through things are replaced by poor substitutes in the name of making the DX better. This, I don't think is a good trend.