That’s also why i love the rust ecosystem. If you have rust installed and have your local dependencies (or only use the standard library), the docs can be generated locally (cargo doc). I certainly remember local manuals helping me out more than once over the years :)
It’s a great feature, but the Rust documentation generally assumes you have a great amount of in-depth knowledge about the language and the specific library you’re using. Often all you’re getting is a list of methods, struts, and traits, and brief descriptions like “frobble_widget frobbles the widget assuming the requirements are met”.
I find the documentation on PHP libraries often a lot better. Technically both support generating the docs from the source code, but the Rust people seem to write worse documentation somehow.
A real shame, because the documentation can contain quick tests that can serve as excellent example code!
Go does this too, and I believe a couple other modern languages do too. Seems like the need for it is real and has been recognised by language authors
deleted by creator
Yes, this is the problem with PHP. It gets a lot of people programming who shouldn’t be. I still have nightmares about the PHP code one of my managers at a previous job wrote.
I’ve heard that a lot, but I think it’s an outdated view.
Programming should be easy, or at least easier. That’s a view shared by everyone who writes and contributes to documentation on all languages and also those who develop the languages as well. (With varying success).
Every damned one of us was a shit coder when we started, that’s part of the process - not least amongst us who are self taught. Yet some go on to do great things and be wonderful coders (including yourself, no doubt).
You had a bad experience, fair enough, but it’s a big brush to tar everyone with. I think everyone should be a programmer. If nothing else it teaches them a little how software actually works and that’s a good thing.
I disagree completely. Sure, there is a learning curve and you’re not going to be a great programmer day one, that is what college and junior programmer positions are for. But the idea that programming can be easy is bullshit.
Programming is inherently difficult, and there is no way to reduce this. Read ‘No Silver Bullet’ by Fred Brooks, it’s as true today as when it was written back in 1986. Not everyone should be a programmer, just like not everyone should be a doctor, or a painter, or a formula 1 driver. People have unique talents and the idea that this is something that everyone should be able to do is frankly ridiculous.
I disagree completely.
Great! It would be a boring world if we all thought alike.
Programming is inherently difficult,
That’s where we differ. I don’t think it is - and I’m not saying that because I think I’m good, it’s because programming is just a different way of thinking - that’s why there’s books like “Zen and the art of computer programming” and “The Tao of programming”. (I haven’t read “No Silver Bullet” but I’ll keep an eye open. I was actually writing code back in 1986 so it might be interesting to compare because I think programming has changed a huge amount in that time)
Not all programming is easy, just as not all of it is hard. The range of this subject is massive, and blanket statements, pro or anti, just don’t cut it when you dig into it.
You can easily find ‘No Silver Bullet’ online http://worrydream.com/refs/Brooks-NoSilverBullet.pdf
He basically splits the complexity of programming into two categories: accidental complexity and essential complexity. The accidental complexity you can fix, it’s the difficulty caused by tooling, programming languages, etc. The essential complexity, that is: the complexity caused by the problem your program is trying to solve, cannot be fixed. To quote the man:
The essence of a software entity is a construct of interlocking concepts: data sets, relationships among data items, algorithms, and invocations of functions. This essence is abstract, in that the conceptual construct is the same under many different representations. It is nonetheless highly precise and richly detailed. I believe the hard part of building software to be the specification, design, and testing of this conceptual construct, not the labor of representing it and testing the fidelity of the representation. We still make syntax errors, to be sure; but they are fuzz compared to the conceptual errors in most systems.
I don’t think it is - and I’m not saying that because I think I’m good, it’s because programming is just a different way of thinking
This different way of thinking is something that some people simply will never get, or not at the right level. I’m certainly not a great programmer but I know from experience I’m above average. I know a lot of programmers that simply cannot grasp things above a certain level of abstraction. These are college-educated programmers with years of experience. The easiest way to tell is that bad programmers turn simple problems into complicated code, and good programmers turn complicated problems into simple code.
Nice quote - but I don’t think it does hold up as truly as it did in the 80s. There is an unimaginable wealth of systems and design tools available now that were not around then. Even something take for granted like a gui schema designer - hell, even SQL itself wouldn’t be around until almost a decade later, and that was partly designed to simplify database queries. Every step like that has simplified what we do today. Debugging tools are light years ahead of when I was writing C in the early 90s. Debugging then was pretty much “try and compile it and then fix the errors”. Now there’s linters, memory profilers, automatic pipelines and all the rest of that. Much of that is offset by the fact we do far more complicated things than we did, and that those very tools mean there’s a lot more to learn and master beyond the mere language.
I do concede and agree with your last paragraph. Design is more important than implementation, and elegance of code and concept is a timeless beauty. One of the hardest things I’ve had to learn is that thinking about coding is often far more productive than actually coding, and too many times I’ve been a busy fool, re-writing and starting over many times because I later found out a better way.
All those tools you mention would fall under the accidental complexity header. There have been many advances in that field. But none of those tools reduce the essential complexity. SQL doesn’t mean you don’t have to think about how you organize your data. You still need to think about things like normalization. Even ORM doesn’t free you from this.
Same goes for debuggers, sure it’s easier to inspect code at runtime but that doesn’t help you design good code.
You can reduce this accidental complexity but in the end there is always the core of the essential complexity. The difference with past decades is that for a simple program the accidental complexity would be a huge part of the total complexity, so in that regard you’re right. It has become a lot easier to write trivial programs where the essential complexity is very low.
This may apply to a lot of hobby-level / beginner projects, but in the end it doesn’t have as much an impact on what we do as professionals. As you said, I spend a lot more time thinking about coding than actually writing code. Especially as I got older and more experienced. As a senior developer I write a fraction of the code I did as a junior, but I’m working on more complicated problems as well.
Exactly, programming shouldn’t be easily accessible. Anybody following a tutorial can make a simple page working. And they think they know programming, get hired by people not knowing any better, and here we are, debugging supid shit instead of doing nice things.
