lysdexic

joined 1 year ago
[–] lysdexic@programming.dev -1 points 1 week 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 4 points 2 weeks ago

Custom methods won't have the benefit of being dealt with as if they shared specific semantics, such as being treated as safe methods or idempotent, but ultimately that's just an expected trait that anyone can work with.

In the end, specifying a new standard HTTP method like QUERY extends some very specific assurances regarding semantics, such as whether frameworks should enforce CRSF tokens based on whether a QUERY has the semantics of a safe method or not.

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

However, we’re still implementing IPv6, so how long until we could actually use this?

We can already use custom verbs as we please: we only need to have clients and servers agree on a contract.

What we don't have is the benefit of high-level "batteries included" web frameworks doing the work for us.

[–] lysdexic@programming.dev 1 points 2 weeks ago* (last edited 2 weeks 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 18 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 3 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

view more: next ›