lysdexic

joined 1 year ago
[–] lysdexic@programming.dev -1 points 5 days ago (1 children)

Does anyone have any good sources or suggestions on how I could look to try and begin to improve documentation within my team?

Documentation in software projecte, more often than not, is a huge waste of time and resources.

If you expect your docs to go too much into detail, they will quickly become obsolete and dissociated from the actual project. You will need to waste a lot of work keeping them in sync with the project, with little to no benefit at all.

If you expect your docs to stick with high-level descriptions and overviews, they quickly lose relevance and become useless after you onboard to a project.

If you expect your docs to document usecases, you're doing it wrong. That's the job of automated test suites.

The hard truth is that the only people who think they benefit from documentation are junior devs just starting out their career. Their need for docs is a proxy for the challenges they face reading the source code and understanding how the technology is being used and how things work and are expected to work. Once they go through onboarding, documentation quickly vanishes from their concerns.

Nowadays software is self-documenting with combination of three tools: the software projects themselves, version control systems, and ticketing systems. A PR shows you what code changes were involved in implementing a feature/fixing a bug, the commit logs touching some component tells you how that component can and does change, and ticketing shows you the motivation and the context for some changes. Automated test suites track the conditions the software must meet and which the development team feels must be ensured in order for the software to work. The higher you are in the testing pyramid, the closer you are to document usecases.

If you care about improving your team's ability to document their work, you focus on ticketing, commit etiquette, automated tests, and writing clean code.

[–] lysdexic@programming.dev 1 points 2 weeks ago* (last edited 1 week ago) (2 children)

Yeah, the quality on Lemmy is nowhere (...)

Go ahead and contribute things that you find interesting instead of wasting your time whining about what others might like.

So far, all you're contributing is whiny shitposting. You can find plenty of that in Reddit too.

[–] lysdexic@programming.dev 2 points 2 weeks ago* (last edited 2 weeks ago)

It’s from 2015, so its probably what you are doing anyway

No, you are probably not using this at all. The problem with JSON is that this details are all handled in an implementation-defined way, and most implementation just fail/round silently.

Just give it a try and send down the wire a JSON with, say, a huge integer, and see if that triggers a parsing error. For starters, in .NET both Newtonsoft and System.Text.Json set a limit of 64 bits.

https://learn.microsoft.com/en-us/dotnet/api/system.text.json.jsonserializeroptions.maxdepth

[–] lysdexic@programming.dev 4 points 2 weeks ago* (last edited 2 weeks ago)

Why restrict to 54-bit signed integers?

Because number is a double, and IEEE754 specifies the mantissa of double-precision numbers as 53bits+sign.

Meaning, it's the highest integer precision that a double-precision object can express.

I suppose that makes sense for maximum compatibility, but feels gross if we’re already identifying value types.

It's not about compatibility. It's because JSON only has a number type which covers both floating point and integers, and number is implemented as a double-precision value. If you have to express integers with a double-precision type, when you go beyond 53bits you will start to experience loss of precision, which goes completely against the notion of an integer.

[–] lysdexic@programming.dev 17 points 2 weeks ago (1 children)
[–] lysdexic@programming.dev 0 points 2 weeks ago

It’s very hard for “Safe C++” to exist when integer overflow is UB.

You could simply state you did not read the article and decided to comment out of ignorance.

If you spent one minute skimming through the article, you would have stumbled upon the section on undefined behavior. Instead, you opted to post ignorant drivel.

[–] lysdexic@programming.dev 4 points 2 weeks ago

I wouldn’t call bad readability a loaded gun really.

Bad readability is a problem cause by the developer, not the language. Anyone can crank out unreadable symbol soup in any language, if that's what they want/can deliver.

Blaming the programming language for the programmer's incompetence is very telling, so telling there's even a saying: A bad workman always blames his tools.

[–] lysdexic@programming.dev 8 points 2 weeks ago* (last edited 2 weeks ago)

Well, auto looks just like var in that regard.

It really isn't. Neither in C# nor in Java. They are just syntactic sugar to avoid redundant type specifications. I mean things like Foo foo = new Foo();. Who gets confused with that?

Why do you think IDEs are able to tell which type a variable is?

Even C# takes a step further and allows developer to omit the constructor with their target-typed new expressions. No one is whining about dynamic types just because the language let's you instantiate an object with Foo foo = new();.

[–] lysdexic@programming.dev 1 points 2 weeks ago (1 children)

I think I could have states my opinion better. I think LLMs total value remains to be seen. They allow totally incompetent developers to occasionally pass as below average developers.

This is a baseless assertion from your end, and a purely personal one.

My anecdotal evidence is that the best software engineers I know use these tools extensively to get rid of churn and drudge work, and they apply it anywhere and everywhere they can.

[–] lysdexic@programming.dev 1 points 2 weeks ago

the first thing I saw is 150 lines of C# reimplementing functions available in the .NET standard lib.

Once again: https://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect

[–] lysdexic@programming.dev 2 points 2 weeks ago (3 children)

They existed before LLMs were spitting code like today, and this will undoubtedly lower the bar for bad developers to enter.

If LLMs allow bad programmers to deliver work with good enough quality to pass themselves off as good programmers, this means LLMs are fantastic value for money.

Also worth noting: programmers do learn by analysing the output of LLMs, just as the programmers of old learned by reading someone else's code.

[–] lysdexic@programming.dev 2 points 2 weeks ago

Claude is laughable hypersensitive and self-censoring to certain words independently of contexts (...)

That's not a problem, nor Claude's main problem.

Claude's main problem is that it is frequently down, unreliable, and extremely buggy. Overall I think it might be better than ChatGPT and Copilot, but it's simply so unstable it becomes unusable.

view more: next ›