submitted 10 months ago by [email protected] to c/[email protected]
top 40 comments
sorted by: hot top controversial new old
[-] [email protected] 47 points 10 months ago* (last edited 10 months ago)

My favorite story about docs is when I tried implementing multithreaded Raycast in Unity.

I needed it to hit multiple targets per ray. Should be pretty easy, after all - there is this parameter right in the constructor:

maxHits: The maximum number of Colliders the ray can hit.

And this is how you use it, straight from the docs:

The result for a command at index N in the command buffer will be stored at index N * maxHits in the results buffer.

If maxHits is larger than the actual number of results for the command the result buffer will contain some invalid results which did not hit anything. The first invalid result is identified by the collider being null. The second and later invalid results are not written to by the raycast command so their colliders are not guaranteed to be null. When iterating over the results the loop should stop when the first invalid result is found.

Well, no. It's not working like that. I was always getting just a single hit, but sometimes, I received two or more hits. After a few days of debugging, I have found a typo in bubblesort, which caused the multiple hits, and I was in fact getting only one hit every time.

Strange, must be a bug then. And then I found it. A bug report from 3 years ago. But it was closed as solved. And the resolution?

I have some news about the issue where RaycastCommand will only return a maximum of 1 hit regardless what you set maxHits to.

According to our developers, each individual raycast in a batch only does a Raycast single in PhysX which will only return the first hit, and not multiple hits if the ray passes through several objects which would require a different raycast function. The documentation simply doesn't explain this very well.

The docs above are from 2021. Three years after this. The fuck "doesn't simply explain it very well"? It literally explains it pretty damn well.

But looks like they've finally changed the docs for 2022+ at least, it did happen few years ago.

[-] Psaldorn 9 points 10 months ago

Ah, reminds me trying to implement multiplayer just as there was some churn regarding unet/llapi/hlapi and every update something would break.

I just gave up. Add it to the failed projects list.

[-] [email protected] 3 points 10 months ago

We've once received an investor offer from a major studio for our game we are making since college in our free time, but the catch was that they wanted us to implement online multiplayer into a coop-only top-down shooter we've been actively making in our free time for the past 4 years at that point.

We ultimately rejected the offer, even though we managed to get a prototype working. MP is such a pain to implement in the first place, and adding it into an almost finished game is near impossible. But, if you ever resume the project you've scratched due to unet being awfull, I highly recommend checking out Mirror. It's free, open-source and has an amazing Discord community - every time I had an issue or needed help with something, there was someone willing to help me there.

[-] Psaldorn 1 points 10 months ago

Sweet thanks!

[-] [email protected] 26 points 10 months ago

Because things keep changing and no one ever updates any docs or guides.

[-] [email protected] 16 points 10 months ago

It would be nice to have a kind of central hub where all the lastest resources are listed.
I could be updated by the community.

Well... one can dream.

[-] [email protected] 14 points 10 months ago

If it's updated by the community, it's probably also created by the community. Instead of dreaming, why not create it?

[-] [email protected] 7 points 10 months ago

Be the change you want to see in the world 🌈

[-] [email protected] 2 points 10 months ago

Someone should build a system that scrapes all open source repositories and uses an LLM to generate up to date documentation, and puts it in one big searchable place

[-] [email protected] 1 points 10 months ago

If using docstrings/docblocks to generate SDK documentation, adding something like an OPA policy to validate their existence and semantic structure could help with coverage. Then we have the issue of accuracy, and that needs humans or AI to weigh in. I have a feeling test-driven development would make this process smoother.

You could also add git hooks to facilitate accountability / run the policies.

[-] [email protected] 19 points 10 months ago

Yeah I built a few react apps that made it to production about 7 years ago.

Now the react syntax I used back then is basically a dead language.

[-] [email protected] 3 points 10 months ago

Pretty typical in web frameworks tbh

[-] jrandiny 17 points 10 months ago

This is why having a dedicated person/team to maintain docs is very important

[-] [email protected] 13 points 10 months ago

I've always felt that programmers need one day out of the week where they explain what their code does to someone dedicated to writing documentation. That way the code is being documented while you still understand what it does and the documentation is constantly being updated.

[-] Gecko 7 points 10 months ago

Also why having doc comments and docs generated from code are super useful. When someone changes the code but not the comment above, it becomes really obvious that something was missed as opposed to having code and doc changes be two separate tasks.

[-] [email protected] 10 points 10 months ago

I know some people don't have the choice but if you do, please choose something better. That garbage does not deserve your effort.

[-] [email protected] 4 points 10 months ago

It's not garbage, it just has some flaws - as does everything. The Spring and Java/JVM ecosystem can be a huge advantage if you know how to use it - which sometimes means diving into library code when docs aren't sufficient.

[-] [email protected] 12 points 10 months ago

As someone who uses Django every day, I can tell you that the code is almost secondary to the amazing documentation. The documentation is such a core part of a framework that I don't see how it can be usable without really good and up to date documentation.

The fact that spring boot's documentation is so bad that it's impossible to even find a reference for a class you're using is, I'm sorry to say, garbage.

[-] [email protected] 9 points 10 months ago* (last edited 10 months ago)

I also feel like agile methodology, which is becoming more common, works against documentation with the fail fast fail often philosophy. If your feedback loop with your stakeholder is rapid, then changes to the design plan are often and rapid as well, which requires more documentation change overhead, which makes documentation even less appealing.

In fact SAFe Agile emphasizes working software over comprehensive documentation.

[-] [email protected] 5 points 10 months ago

SAFe Agile can go fuck itself. It's the worst of everything, isn't actually agile and is a disease infesting corporations who don't know any better.

All these methodologies and philosophies are all invented so a few people can sell books, training and lectures.

[-] [email protected] 2 points 10 months ago

I feel like agile is better for Apps (which requires very little documentation usually, no one wants to read a help guide for an app), compared to Libraries which are literally unusable without documentation.

[-] theGimpboy 6 points 10 months ago

There's a lot of things you can criticize Microsoft for but their documentation is 🧑‍🍳

[-] [email protected] 6 points 10 months ago

Spring Boot is the worst for this. It seems like every minor update deprecates some security classes which yields a few hours of effort to implement the same damn thing every week

[-] [email protected] 4 points 10 months ago

I've worked in both android and spring boot and rewriting your security to use a filter chain is nothing* compared to the shenanigans google likes to pull. Keeping up with the deprecations and imaginary "best practices" is half the job. It's like someone combined the worst parts of react with the worst Java timeline and forced people to write inscutable spaghetti that's completely impractical/impossible to test.

*there are valid criticisms of spring security, but I think this particular change improved things, even if it felt pointless

[-] [email protected] 2 points 10 months ago

Man, early dotnet core was like that, but thankfully it's been stable since 3 or 5.

[-] [email protected] 6 points 10 months ago

I'm all for progress in technology but sometimes there's a disconnect between planning/budgeting and how it progresses way so fast like when it has a large corporation supporting it's development but folks are writing apps with like two person teams and sustaining these projects for years and need to decide "is today the day I rewrite the whole project to bring it up to date or do I fix that one bug and implement that feature the customer wants?". I swear just keeping code up to date is at least one or two FTEs but it's never included in a budget.

[-] [email protected] 5 points 10 months ago

Welcome to the churn where everything got replaced every 5 years and old stuff re-appear again as the hot new stuff every 15 years.

[-] [email protected] 5 points 10 months ago

I'm sticking around to see if someone has a good spring tutorial.

[-] [email protected] 4 points 10 months ago
[-] 9point6 6 points 10 months ago

Someone's trying to be productive in Java

[-] [email protected] 1 points 10 months ago

They should have used Quarkus /s

[-] [email protected] 4 points 10 months ago

Unreal docs entered the chat

[-] [email protected] 4 points 10 months ago

Because developers don't bother with documentation. They either assert it's self documenting or they assert whatever it is was always intended to be temporary so it's not worth documenting.

[-] lorkano 1 points 10 months ago

If you eventually get to the class that can replace it's not that bad. The worst case is when there is no replacement class at all

[-] [email protected] 1 points 10 months ago
[-] buffet 0 points 10 months ago
[-] [email protected] 1 points 10 months ago
[-] buffet 1 points 10 months ago
[-] [email protected] 1 points 10 months ago

Not much not much

[-] [email protected] 1 points 10 months ago

After 10+ years doing go, js, and ruby, my company is moving me to a Java spring team.

I’ve been looking at baeldung tutorials to get up to speed with spring and reactor and it’s been a pretty good resource.

this post was submitted on 03 Aug 2023
466 points (99.4% liked)

Programmer Humor

17958 readers
3298 users here now

Welcome to Programmer Humor!

This is a place where you can post jokes, memes, humor, etc. related to programming!

For sharing awful code theres also Programming Horror.


founded 1 year ago