Do all the things like ++ or -- rants, post your own rants, comment on others' rants and build your customized dev avatarSign Up
From the creators of devRant, Pipeless lets you power real-time personalized recommendations and activity feeds using a simple APILearn More
..or let the code be clear enough to be the documentation.
Yes, it can be done. Yes it has been done.
@devdiddydog 🤭nah, that in its own is beyond this devs ability.
Magic numbers, magic numbers everywhere.
Some relate to expected row from a db.... #wcgw.
Some are config values without their constants, just the number.
It's like a shit storm of mess.
@C0D4 Haha, that's pretty extreme, I have also lost some hair over code similar to that.
At least we can rest assure those responsible will end up in hell debugging Excel macros for eternity.
@devdiddydog that’s not a very reassuring thought if that dev happens to be yourself 😅
I’m pretty sure very few of us wrote self-documenting code when we started out. And it happens that you have to deal with that code much later on and wish whoever wrote that piece of garbage rots in hell - until you git blame and find out it was a younger yourself…
Also use graphs as much as you can. Not necessarily UML, but any graph that gives perspective on the shit you've done. Graph saves souls, kids!
@NoMad 😂 you're hired.
Even just the basic high level business flow would be enough to understand what this is trying to achieve.
Think of an API where every user gets a slightly different payload in the response, and I don't mean data, actual payload structure changes 😓
@C0D4 worked with them. Example; Telstra and Optus APIs are (or used to be) very different. But even their fucking responses used to have missing fields or other fuckups that meant I had to dissect the response and prepare for every fucking fuckup scenario... And even then, some responses were... Just pure magic. 🤦
@NoMad I've managed to steer away from integrating with telcos so far. There's a portion of the business that's growing in that front so that day may arise down the line.
Payment gateways, CRM/ERPs and "bespoke" B2B integrations are the usual madness I deal with.
@C0D4 when you have time, plz explain to me what these bespoke stuff are. I'd appreciate it!
donuts242781y@devdiddydog but the app is 1 of N... How do you communicate that in code?
Code docs comments and clean code is good.
But I don't see how to explain... In order for the whole thing to work (including defining what the whole thing is) you need to run ...
Can't put that in just the code.
Inxentas8141yUnder capitalism, how are the struggles of my old employer, who doesn't understand what the value of documentation is and never asks I write some... MY problem, exactly? I understand working without docs is terrible but hey, that's what you get when you work for my employer.
@devdiddydog C++ 98 would like a word.
Joking aside yeah it is better to make sure code us as self-explanatory as possible
Clean code and unit tests are a great way to document. But environment/ci/cd configs...write that shit down for others to find after you're gone
@onetrickpony clean code helps, but only to a point, yes you can read the code and get a feel for what's going on, this is useful for changing things. But recreating what's already there without affecting end users beyond giving them a new endpoint plus standardising about 35 different responses into a single call rather then having "generateUserResponseA()" in the db calling a literal method in the code base through runtime injection 😂😂😂😂😂
Most people know sql injection, but fucking backend code injection... that's going that step further.
Unit tests will only tell you something works as intended, they won't tell you what is going on outside of their test, assuming you have tests at all 🤣
Just to clear something up: yes, put a bit of effort in to document your system as a whole. And yes, use some graphics. And no, don't use Paint or a tool where you can't open and edit your drawing as your architecture changes - because it will. It should.
But if you have modules or microservices that are named appropriately, clearly showing which context they belong to, spend an extra 3 seconds when you name variables and methods, keep your classes reasonably compact, don't chain your methods to the point where you lose track of what's happening and in the inevitable situations where a short explanation is needed just put a comment in.
It's possible. And it has been done! :D I have written plenty of code that breaks all of these guidelines and am as guilty as the rest of you. I just meant that we should encourage this before encouraging more documentation.
anniepotts01yUse graphs as much as you can.
Ok you fucks that don't believe in documentation - me included.
Document your shit, because one day, one day some dumb fuck is going to have to recreate your over engineered bullshit of a system and scale it up.
What would fucking be useful right now is ANY god forsaken insight into what in the flying fuck your code is doing, or not doing, or why it makes queries to a database with no fucking records in it 🤦♂️ and then attempts to use that data... in case it did exist.
There's nothing like unpicking a mess of bullshit, and documenting it, and then have to remake it on a new platform.
Documention saves lives kids, maybe your own life one day😬
comments don't lie
save a life - write a spec