Any company that hides their documentation has an awful product that they are actually embarrassed about, from a tech perspective. They are hiding it because they are afraid to show it.
I’ve seen this so many times, and it’s a big red flag.
These companies work on the basis of selling their product the old-fashioned way, directly to management with sales-people and business presentations and firm handshakes, and then once you’re sold then developers (which management doesn’t care about by the way) have to do the odious task of getting everything working against their terrible and illogical API. And when you need help implementing, then your single point of contact is one grumpy-ass old dev working in a basement somewhere (because they don’t care about their own devs either) and he’s terribly overstretched due to the number of other customers he’s also trying to help, because their implementation is so shitty.
Conversely, public documentation is a great sign that companies took a developer-led approach to designing their solution, that it will be easy to implement, that they respect the devs within their own company, and they will also respect yours.
When I am asked to evaluate potential solutions for a problem, Public docs is like the number one thing I care about! It’s just that significant.
Side story - I once worked with one of these shitty vendors, and learned from a tech guy I’d made friends with that the whole company was basically out of office on a company-paid beach holiday - EXCEPT for the dev team. Management, sales, marketing, finance, they all got a company trip, but the tech peeps had to stay at home. Tells you everything you need to know about their management attitude towards tech.
Been there many times. Had one case where support had to through the reseller who sold licenses in our country. Actual people who knew what they were talking about was tier 3.
We had a bug and were trying to report it and get a fix or workaround. Just told no, we’re doing it wrong. After a lot of back and forth we had to pay for an “expert” to fly over and show us what we were doing wrong. Turns out he wasn’t an expert, he was a salesmen. Made a demo for us on the flight and the first time he ran it was in our meeting room on projector.
Failed in exactly the way we had been saying. It was very satisfying.
Finally he phoned the dev team who confirmed the docs were wrong and we couldn’t do what we were trying.
Haha yep. Not the support process you want. Glad you managed to let them eat some humble pie at least.
The support process you want is this: “We’ll make you a channel on our Slack, if you’ve got any issues you can talk with our devs direct!” - yes please!
Fun story! At a conference, I asked this vendor (the company collapsed now) if I can see their documentation. The obvious sales person made a big stink how it’s only for paid customers and I can see it when I paid.
I told him how stupid it was since his competitors have their docs open.
During a conference’s event where they parade their sponsors, the vendor got on stage and called me out with “And paid customers will have a wealth of support, like developer documentation… Especially for you [name]”.
In my nerd rage, I shouted from the audience “What kind of shit software is afraid to share their developer docs publicly?” I was escorted out by security.
And during the night event when everyone mingles (including sponsors), the guy didn’t show up. And apparently, news got around where by the last day of the event, the entire booth was taken down.
I dunno if it was me shouting and everyone agreeing with me, or the conference realizing that attacking a paid member of the audience wasn’t a good idea and told him to leave.
Either way… Tell it to their faces when their product isn’t dev friendly. These charlatans seem to get bolder and bolder with their garbage.
I absolutely agree, and I too hate this stupid idea of “good code documenting itself” and “comments being unnecessary”.
I have a theory where this comes from. It was probably some manager, who has never written a single line of code, who thought that comments were a waste of time, and employees should instead focus on writing code. By telling them that “good code documents itself”, they could also just put the blame on their employees.
“Either you don’t need comments or your code sucks because it’s not self-documenting”
Managers are dumb, and they will never realize that spending a bit of time on writing useful comments may later actually save countless hours, when the project is taken over by a different team, or the people who initially created it, don’t work at the company anymore.
I’ve never had a manager that was even aware of the comments vs. no comments issue. If I ever had, I would have just told them that a lack of comments makes the original coder harder to replace.
Code should always by itself document the “how” of the code, otherwise the code most likely isn’t good enough. Something the code can never do is explain the “why” of the code, something that a lot of programmers skip. If you ever find yourself explaining the “how” in the comments, maybe run through the code once more and see if something can be simplified or variables can get more descriptive names.
For me, that’s what was originally meant with self-documenting code. A shame lazy programmers hijacked the term in order to avoid writing any documentation.
I don’t think they’re lazy, I think they’re not good writers. Not being able to write well is very common among programmers (not having to communicate with written language is one reason a lot of people go into coding) and in my experience the Venn diagrams for “not a good writer” and “thinks comments are unnecessary” overlap perfectly.
And isn’t it such a dangerous overlap! The coder whose writing (in their native language) is unclear, repetitive, convoluted, or hard to follow too often produces code with the same qualities. It’s even worse when the same coder believes “code is self-documenting” without considering why. Code self-documents with careful and deliberate effort, and in my experience, it is the really good writers who are most capable of expressing code in this way.
Its definitely a balance. Good code shouldn’t need much commenting, but sometimes you have to do something for a reason that isn’t immediately obvious and that’s when comments are most useful. If you’re just explaining what a snippet does instead of why you’re doing it that way, there’s probably more work to be done.
Comment should describe “why?”, not “how?”, or “what?”, and only when the “why?” is not intuitive.
The problem with comments arise when you update the code but not the comments. This leads to incorrect comments, which might do more harm than no comments at all.
E.g. Good comment: “This workaround is due to a bug in xyz”
Bad comment: “Set variable x to value y”
Note: this only concerns code comments, docstrings are still a good idea, as long as they are maintained
In my opinion, it strongly depends on what you’re coding.
Low-level code where you need to initialize array indices to represent certain flags? Absolutely comment the living shit out of that. → See response.
High-level code where you’re just plumbing different libraries? Hell no, the code is just as easily readable as a comment.
I do also think that, no matter where you lie in this spectrum, there is always merit to improving code to reduce the need for documentation:
Rather than typing out the specification, write a unit/integration test.
Rather than describing that a function should only be called in a certain way, make it impossible to do it wrongly by modelling this in your type system.
Rather than adding a comment to describe what a block of code does, pull it out into a separate function.
Rather than explaining how a snippet of code works, try to simplify it, so this becomes obvious.
The thing with documentation is that it merely makes it easier to learn about complexity, whereas a code improvement may eliminate this complexity or the need to know about it, because the compiler/test will remember.
This does not mean you should avoid comments like they’re actively bad. As many others said, particularly the “why” is not expressable in code. Sometimes, it is also genuinely not possible to clean up a snippet of code enough that it becomes digestable.
But it is still a good idea, when you feel the need to leave a comment that explains something else than the “why”, to consider for a moment, if there’s not some code improvement you should be doing instead.
Hard disagree on your first point. Name the flags with descriptive name, move this initialisation to a function, and there you go, self-documented and clear code.
Hmm, maybe my opinion is just shit in that regard. I don’t code terribly much low-level, so I’m probably overestimating the complexity and underestimating the options for cleaning things up.
That was kind of just a random example, I felt like there were many more cases where low-level code is complex, but I’m probably basing this off of shitty low-level code and forgetting that shitty high-level code isn’t exactly a rarity either.
I’m with you but sometimes you don’t have the chance in low level. Max you can do is create local variables just so the bits you’re XORing are more obvious. And whenever you’re working with something where that’d be wasteful and the compiler doesn’t rid if it, you’re better off with comments (which you need to maintain, ugh)
Good code is self documenting as in you don’t need to describe what it is doing and it is clear to read. Whoever says that and isn’t just repeating what they heard understands that whenever you are doing something not explicit in the code it should be on a comment.
Workarounds and explaining you need to use this structure instead of another for some reason are clear examples, but business hints are another useful comment. Or sectioning the process (though I prefer descriptive private functions or pragma regions for that).
It also addresses the hint that the code should be readable because you’re not going to have comments to explain spaghetti. Just a hint, doesn’t prevent it. Others also said it, comments are easier to get outdated as you don’t have the compiler to assist. And outdated comments lead to confusion.
I follow these simple rules and encourage my colleagues to do so
If I’m just shuffling jsons, then yes, the code should be self documented. If it’s not, the code should be rewritten.
If I implement some complex logic or algorithm, then the documentation should be written both to tests and in the code. Tests should be as dull as possible.
If I write multithreading, the start, interruption, end, and shared variables should be clearly indicated by all means that I have: comment, documentation, code clearness. Tests should be repeated and waits should not be over 50ms.
What they mean is that the variable names and function names are documentation.
For example changing “for( i in getList() )” to “for( patient in getTodaysAppointments() )” is giving the reader more information that might negate the need for a comment.
I actually agree that “good enough” code can be self-documenting, but it isn’t always enough to achieve my goal which is to make the code understandable to my audience with minimal effort. With that goal in mind, I write my code as I would write a technical document. Consider the audience, linear prose, logical order, carefully selected words, things like that… In general, I treat comments as a sort of footnote, to provide additional context where helpful.
There are limits to self-documenting code, and interfaces are a good example. With interfaces, I use comments liberally because so many of the important details about the implementation are not obvious from the code: exactly how the implementation should behave, expected inputs and outputs under different scenarios, assumptions, semantic meaning, etc. Without this information, an implementation cannot be tested or verified.
Have you ever worked in a place where every function/field needed a comment? Most of those comments end up being “This is the <variable name>, or this does <method name>”. Beyond, being useless, those comments are counter productive. The amount of screen space they take up (even if greyed out by the IDE) significantly hurts legability.
I get what you’re saying. Perhaps I just haven’t had too many variables and such that have had such comments. VsCode shows the comments on hover when you’re in other parts of the code base. Which makes most any comment useful because something that is obvious in one part of the code isn’t immediately obvious in another. Though, that necessitates making comments that actually help you figure that out.
I have worked on larger older projects. The more comments you have, the larger the chance that code and comment diverge. Often, code is being changed/adapted/fixed, but the comments are not. If you read the comments then, your understanding of what the code does or should do gets wrong, leading you on a wrong path. This is why I prefer to have rather less comments. Most of the code is self a explanatory, if you properly name your variables, functions and whatever else you are working with.
One example for self documenting code is typing. If you use a language which enforces (or at least allows, as in Python 3.8+) strong typing and you use types pro actively, this is better than documentation, because it can be read and worked with by the compiler or interpreter. In contrast to documenting types, the compiler (or interpreter) will enforce that code meaning and type specification will not diverge. This includes explicitly marking parameters/arguments and return types as optional if they are.
I think no reasonable software developer should work without enforced type safety unless working with pure assembler languages. Any (higher) language which does not allow enforcing strong typing is terrible.
IDE is one thing, Go refuses to compile. Like calm down, I’m going to use it in a second. Just let me test the basics of my new method before I start using this variable.
Or every time you add or remove a printf it refuses to compile until you remove that unused import. Please just fuck off.
Yeah I think it’s trauma due to C/C++'s awful warning system, where you need a gazillion warnings for all the flaws in the language but because there are a gazillion of them and some are quite noisy and false positives prone, it’s extremely common to ignore them. Even worse, even the deadly no-brainer ones (e.g. not returning something from a function that says it will) tend to be off by default, which means it is common to release code that triggers some warnings.
Finally C/C++ doesn’t have a good packaging story so you’ll pretty much always see warnings from third party code in your compilations, leading you to ignore warnings even more.
Based on that, it’s very easy to see why the Go people said “no warnings!”. An unused variable should definitely be at least a warning so they have no choice but to make it an error.
I think Rust has proven that it was the wrong decision though. When you have proper packaging support (as Go does), it’s trivial to suppress warnings in third party code, and so people don’t ignore warnings. Also it’s a modern language so you don’t need to warn for the mistakes the language made (like case fall through, octal literals) because hopefully you didn’t make any (or at least as many).
LLMs are just very complex and intricate mirrors of ourselves because they use our past ramblings to pull from for the best responses to a prompt. They only feel like they are intelligent because we can't see the inner workings like the IF/THEN statements of ELIZA, and yet many people still were convinced that was talking to them. Humans are wired to anthropomorphize, often to a fault.
I say that while also believing we may yet develop actual AGI of some sort, which will probably use LLMs as a database to pull from. And what is concerning is that even though LLMs are not "thinking" themselves, how we've dived head first ignoring the dangers of misuse and many flaws they have is telling on how we'll ignore avoiding problems in AI development, such as the misalignment problem that is basically been shelved by AI companies replaced by profits and being first.
HAL from 2001/2010 was a great lesson - it's not the AI...the humans were the monsters all along.
I wouldn't be surprised if someday when we've fully figured out how our own brains work we go "oh, is that all? I guess we just seem a lot more complicated than we actually are."
If anything I think the development of actual AGI will come first and give us insight on why some organic mass can do what it does. I've seen many AI experts say that one reason they got into the field was to try and figure out the human brain indirectly. I've also seen one person (I can't recall the name) say we already have a form of rudimentary AGI existing now - corporations.
Something of the sort has already been claimed for language/linguistics, i.e. that LLMs can be used to understand human language production. One linguist wrote a pretty good reply to such claims, which can be summed up as “this is like inventing an airplane and using it to figure out how birds fly”. I mean, who knows, maybe that even could work, but it should be admitted that the approach appears extremely roundabout and very well might be utterly fruitless.
That’s why consciousness is “magical,” still. If neurons ultra-basically do IF logic, how does that become consciousness?
And the same with memory. It can seem to boil down to one memory cell reacting to a specific input. So the idea is called “the grandmother cell.” Is there just 1 cell that holds the memory of your grandmother? If that one cell gets damaged/dies, do you lose memory of your grandmother?
And ultimately, if thinking is just IF logic, does that mean every decision and thought is predetermined and can be computed, given a big enough computer and the all the exact starting values?
Absolutely! It’s a common misconception about neurons that I see in programming circles all the time. Before my pivot into programming I was pre-med and a physiology TA - I’ve always been interested in neurochemistry and how the brain works.
So I try and keep up with the latest about the brain and our understanding of it. It’s fascinating.
Though I should point out that the virtual neurons in LLMs are also noisy and sensitive, and the noise they use ultimately comes from tiny fluctuations of random atomic noise too.
Physics and more to the point, QM, appears probabilistic but wether or not it is deterministic is still up for debate. Until such a time that we develop a full understanding of QM we can not say for sure. Personally I am inclined to think we will find deterministic explanations in QM, it feels like nonsense to say that things could have happened differently. Things happen the way they happen and if you would rewind time before an event, it should resolve the same way.
Fair - it’s not that we know it’s not: it’s that we don’t know that it is.
Probabilistic is equally likely as deterministic - we’ve found absolutely nothing disproving probabilistic models. We’ve only found reinforcement for those models.
It’s unintuitive to humans so of course we don’t want to believe it. It remains to be seen if it’s true.
Its worth mentioning that certain mainstream interpretations are also concretely deterministic. For example many worlds is actually a deterministic interpretation, the multiverse is deterministic, your particular branch simply appears probabilistic. Much more deterministic is Bohmian mechanics. Copenhagen interpretation, however, maintains randomness.
Sure but interpretations like pilot wave have more evidence against them than for them and while multiverse is deterministic it’s only technically so. It’s effectively probabilistic in that everything happens and therefore nothing is determined strictly by current state.
Individual cells do not encode any memory. Thinking and memory stem from the great variety and combinational complexity of synaptic interlinks between neurons. Certain “circuit” paths are reinforced over time as they are used. The computation itself (thinking, recalling) then is “just” incredibly complex statistics over millions of synapses. And the most awesome thing is that all this happens through chemical reaction chains catalysed by an enormous variety of enzymes and other proteins, and through electrostatic interactions that primarily involve sodium ions!
Seth Anil has interesting lectures on consciousness, specifically on the predictive processing theory. Under this view the brain essentially simulates reality as a sort of prediction, this simulated model is what we, subjectively, then perceive as consciousness.
“Every good regulator of a system must be a model of that system“. In other words consciousness might exist because to regulate our bodies and execute different actions we must have an internal model of ourselves as well as ourselves in the world.
As for determinism - the idea of libertarian free will is not really seriously entertained by philosophy these days. The main question is if there is any inkling of free will to cling to (compatibilism), but, generally, it is more likely than not that our consciousness is deterministic.
Its not that odd if you think about it. Everything else in this universe is deterministic. Well, quantum mechanics, as we observe it, is probabilistic, but still governed by rules and calculable, thus predictable (I also believe it is, in some sense, deterministic). For there to be free will, we need some form of “special sauce”, yet to be uncovered, that would grant us the freedom and agency to act outside of these laws.
This had an interesting part in Westworld, where at one point they go to a big database of minds that have been “backed up” in a sense, and they’re fairly simple “code books” that define basically all of the behaviors of a person. The first couple seasons have some really cool ideas on how consciousness is formed, even if the later seasons kind of fell apart IMO
It isnt so much “we" as in humanity, it is a select few very ambitious and very reckless corpos who are pushing for this, to the detriment of the rest (surprise).
If “we” were able to reign in our capitalists we could develop the technology much more ethically and in compliance with the public good. But no, we leave the field to corpos with delusions of grandeur (does anyone remember the short spat within the openai leadership? Altman got thrown out for recklessness, investors and some employees complained, he came back and the whole more considerate and careful wing of the project got ousted).
I find that a lot of the reasons people put up for saying “LLMs are not intelligent” are wishy-washy, vague, untestable nonsense. It’s rarely something where we can put a human and ChatGPT together in a double-blind test and have the results clearly show that one meets the definition and the other does not. Now, I don’t think we’ve actually achieved AGI, but more for general Occam’s Razor reasons than something more concrete; it seems unlikely that we’ve achieved something so remarkable while understanding it so little.
I recently saw this video lecture by a neuroscientist, Professor Anil Seth:
He argues that our language is leading us astray. Intelligence and consciousness are not the same thing, but the way we talk about them with AI tends to conflate the two. He gives examples of where our consciousness leads us astray, such as seeing faces in clouds. Our consciousness seems to really like pulling faces out of false patterns. Hallucinations would be the times when the error correcting mechanisms of our consciousness go completely wrong. You don’t only see faces in random objects, but also start seeing unicorns and rainbows on everything.
So when you say that people were convinced that ELIZA was an actual psychologist who understood their problems, that might be another example of our own consciousness giving the wrong impression.
Personally my threshold for intelligence versus consciousness is determinism(not in the physics sense… That’s a whole other kettle of fish). Id consider all “thinking things” as machines, but if a machine responds to input in always the same way, then it is non-sentient, where if it incurs an irreversible change on receiving any input that can affect it’s future responses, then it has potential for sentience. LLMs can do continuous learning for sure which may give the impression of sentience(whispers which we are longing to find and want to believe, as you say), but the actual machine you interact with is frozen, hence it is purely an artifact of sentience. I consider books and other works in the same category.
I’m still working on this definition, again just a personal viewpoint.
I read this question a couple times, initially assuming bad faith, even considered ignoring it. The ability to change, would be my answer. I don’t know what you actually mean.
I do think we’re machines, I said so previously, I don’t think there is much more to it than physical attributes, but those attributes let us have this discussion. Remarkable in its own right, I don’t see why it needs to be more, but again, all personal opinion.
I don’t necessarily disagree that we may figure out AGI, and even that LLM research may help us get there, but frankly, I don’t think an LLM will actually be any part of an AGI system.
Because fundamentally it doesn’t understand the words it’s writing. The more I play with and learn about it, the more it feels like a glorified autocomplete/autocorrect. I suspect issues like hallucination and “Waluigis” or “jailbreaks” are fundamental issues for a language model trying to complete a story, compared to an actual intelligence with a purpose.
LLMs are just very complex and intricate mirrors of ourselves because they use our past ramblings to pull from for the best responses to a prompt. They only feel like they are intelligent because we can’t see the inner workings
I want a strongly pro-vaccine culture, but whether or not to have vaccines mandated by the government is a tough dilemma for me.
I expect America’s overall health to improve and catch up with the rest of the world under RFK Jr. because of his support for vaccine/drug testing that’s free from corporate capture and his ambition to mitigate chronic disease.
I can respond to your point about conspiracy theories if you’re more specific.
If all of your supporters think vaccines cause diseases, if you're elected you're going to need to satisfy them by acting on those beliefs.
I think, in the abstract, you're right - having any sort of health procedure mandated by the govt is extremely problematic. However hugely communicable diseases are a big caveat to that principle, and we have been doing something about that for a long long time.
Typhoid Mary
was forcibly detained because, over and over again, she kept spreading the disease. Several different times, bird flu was halted before it could get too widespread because of govt mandated culls. Smallpox was completely eradicated because of vaccine efforts.
Imagine if in any of those cases people said 'freedom' was primary and prevented coercion for vaccines. The death and injury toll would be much higher by today, including those of the young and the immunocompromised.
Right now my gut reaction is that local governments, but not higher levels of authority, should be able to do what was done to Typhoid Mary, until we have sufficiently convenient and effective ways to be protected from contagious diseases without the cooperation of other people.
Lemmy really needs pixelfed’s naive bayes spam detection, it would be able to easily classify the new accounts after classifying one post as spam, then it would be 0 seconds wasted.
I’m pretty sure this is aimed at websites that have a “download” or “get x now” link on their website that just takes you to a git hub page with no obvious download section. It isn’t uncommon, and it can be frustrating. At the very least, it’s a bad user experience.
The medium internet user doesn’t even know what git is, so I think it is very likely that a lot of people don’t understand the way github works and are very upset by how “difficult” it can be to get an installer from it.
I think the text should be combined into one sentence, which would be run-on but still give the impression that both images refer to one person, as it should be.
The first step to correction is understanding there is a problem in the first place. This is quite constructive, it may just not feel like it is because it’s framed combatively.
You’re doing it wrong is the phrase that lets teachers teach at one of the most basic levels.
The public is essentially a self teaching teacher, so this is just the process of public correction happening. It may look/feel like public shaming, and it may be if they’re going too far, but that is the mechanism that I think is playing out here.
Does that framing make it any more palatable to you or does it still seem unnecessarily disrespectful?
To me, constructive criticism means that the criticism doesn’t just point out failure, but that it then also shows how to correct that failure.
By itself, “you’re doing it wrong” is just destructive: it takes something apart, it destroys it. Without a subsequent “and here’s how you would do it right,” it doesn’t become constructive, it doesn’t help in putting things back together in the correct way.
Sure, as a first step, “you’re doing it wrong” is completely justified when something is actually wrong.
But without the second step - the constructive part - it just doesn’t constitute constructive criticism. By itself, it’s just criticism.
Ah I get that, like the frustration of a sociological paper pointing out a societal issue but offering no steps on how to solve it due to fixes being out of scope (utterly infuriating lol).
I still think the criticism is valid, but I do think I agree in that the criticism could be more constructive… But I still think laying the foundation of the argument, so to speak, is still constructive even though it may not go as far as one may need for it to cross the threshold back into polite…
I am still convinced this is a knee jerk feeling issue more than anything truly being amiss, but I have been wrong before. What do you think?
I agree it probably is a definitions thing, I’m very pedantic sometimes and it feels like my definition of constructive is much more optimistic/wider/encompassing than yours. That doesn’t mean that my definition is right or that your position is wrong though, that’s just what I think is going on here.
I’m sure it didn’t go well. If it was somehow framed in a sycophantic way where the police were led to believe it was their idea, I’m sure it would have gone better. Wait that might not be too difficult to do.
Na. If it’s British police it’s just an excuse. All they’re there for after all these years of Tory cuts is to give you a reference number so you can make an insurance claim.
programmer_humor
Top
This magazine is from a federated server and may be incomplete. Browse more on the original instance.