Join devRant
Do all the things like
++ or -- rants, post your own rants, comment on others' rants and build your customized dev avatar
Sign Up
Pipeless API

From the creators of devRant, Pipeless lets you power real-time personalized recommendations and activity feeds using a simple API
Learn More
Search - "documentation fail"
-
I FUCKING HATE IT WHEN I HAVE TO BUILD SOMETHING FROM SOURCE!!!!
So I wanted to install a package with pip. Shouldn't be that difficult, right? RIGHT? Lmao
Things I encountered on this adventure in no particular order:
- multiple undocumented dependencies, only explained on stackoverflow or some github issues
- inconsistent and outdated documentation spread over multiple pages on multiple websites
- Python version can't be too old or too new
- other external software version incompatibilities
- Build process that takes several minutes just to fail, then try again and fail with exactly the same outcome after a few minutes
- fucking SVN is needed?!?!?!
- VS Code is needed for completely manual build ????
- cmd/powershell incompatibilites
- required reboots
At some point I just gave up... Now I don't even remember what I crap I installed that I don't need anymore.
Please for the love of god provide prebuild packages or at least a very SIMPLE build process -_-8 -
Today after longer vacation I came back to work.
Edit: wrote this rant long time ago, but never finished. Was too pissed.
Some easy meetings, then wanted to start on an easy job.
Just migrating some things from bash regex voodoo to proper tools like JQ.
Finished in roughly 1 h. Lovely.
Made some tea, ate some cookies.
Set up dev environment, found no documentation what so ever, got it running after half an hour.
Annoying, but ok.
Then I tried my scripts...
They worked... Except they didn't.
Console log empty, response code 200 with state: GENERATE_NO_FILES.
Eh. Fuck you. Just fuck you.
Fixed the logging configuration, which was broken since uhm... 2 years plus?
Well... Another half another hour gone...
Kinda pissed now.
Still script return failed...
Poking and trying to sprinkle debug all over that shit cause everything seems ... An incohesive, inconsistent diarrhea.
3 hours later...
Made the ticket to rewrite it.
I did nothing wrong at all.
The API just has no workflow at all. The
*seperate* API calls have to be in an **specific** order - as otherwise the generation will fail, as the prerequisites for the generation are not fulfilled.
Yeah. Completely logical. Especially not to give out any kind of warning or an error message like requirements not met, blablabla.
I drank that evening 2 six packs of beer. I was raging mad....
Then gave that shit to another manager, as I never want to touch that nuclear waste again....
How can someone be so brain damaged -.-1 -
So, just to recap if you missed the last few episodes. I've been a web developer for years. But I decided to get a degree and go to uni.
Also I am firmly on the fewer comments side of the debate about self-documenting code. Even though I usually rephrase it and say method and variable names are comments. Basic idea: something is unclear, you should leave a comment. But, before you leave a comment, take a good look at your method. Can you rename a variable? Maybe the method name? Maybe extract a method into smaller methods so it doesn't need a comment? And only if you fail to do so, leave a comment.
Alright, now that we rehashed that, uni coding makes no bloody sense.
There is code that is abbreviated to the max (or min).
And then, they need everything commented. I mean, why do that? Why call the parameters a and b instead of base and exponent. And then say:
"But write a whole article about it above the method". Like:
a is the base for a power operation.
b is the exponent for a power operation.
return int representing a to the power of b
How about just do this:
public static int power(int base, int exponent).
How is this not the same documentation?
Is it because we're at a uni, a place for smart people and smart people shouldn't have an issue keeping a mental map between the variables and their meaning?
Or is it because they are all mathematicians. All respect to applied mathematics. I mean, the function about exponent calculation, I was not aware that it could be that effective. But on the other hand, keep mathematicians away from programming. I get it, writing maths per hand doesn't have intellisense and therefore you don't want to write long variable names. It's and old tradition. Yada yada, yah.
But programming is not maths. And maths shouldn't be maths like that. Right naming makes it simpler. It might still be a while until we all LaTeX rather than handwrite and be able to give maths right naming schemes, but programming is beyond the point. Calling the array you handing in a function A and the one that you're returning D makes no fucking sense.4 -
#Suphle Rant 6: Deptrac, phparkitect
This entry isn't necessarily a rant but a tale of victory. I'm no more as sad as I used to be. I don't work as hard as I used to, so lesser challenges to frustrate my life. On top of that, I'm not bitter about the pace of progress. I'm at a state of contentment regarding Suphle's release
An opportunity to gain publicity presented itself last month when cfp for a php event was announced last month. I submitted and reviewed a post introducing suphle to the community. In the post, I assured readers that I won't be changing anything soon ie the apis are cast in stone. Then php 7.4 officially "went out of circulation". It hit me that even though the code supports php 8 on paper, it's kind of a red herring that decorators don't use php 8 attributes. So I doubled down, suspending documentation.
The container won't support union and intersection types cuz I dislike the ambiguity. Enums can't be hydrated. So I refactored implementation and usages of decorators from interfaces to native attributes. Tried automating typing for all class properties but psalm is using docblocks instead of native typing. So I disabled it and am doing it by hand whenever something takes me to an unfixed class (difficulty: 1). But the good news is, we are php 8 compliant as anybody can ask for!
I decided to ride that wave and implement other things that have been bothering me:
1) 2 commands for automating project setup for collaborators and user facing developers (CHECK)
2) transferring some operations from runtime to compile/build TIME (CHECK)
3) re-attempt implementing container scopes
I tried automating Deptrac usage ie adding the newly created module to the list of regulated architectural layers but their config is in yaml, so I moved to phparkitect which uses php to set the rules. I still can't find a library for programmatically updating php filed/classes but this is more dynamic for me than yaml. I set out to implement their library, turns out the entire logic is dumped into the command class, so I can neither control it without the cli or automate tests to it. I take the command apart, connect it to suphle and run. Guess what, it detects class parents as violations to the rule. Wtflyingfuck?!
As if that's not bad enough, roadrunner (that old biatch!) server setup doesn't fail if an initialization script fails. If initialization script is moved to the application code itself, server setup crumbles and takes the your initialization stuff down with it. I ping the maintainer, rustacian (god bless his soul), who informs me point blank that what I'm trying to do is not possible. Fuck it. I have to write a wrapper command for sequentially starting the server (or not starting if initialization operations don't all succeed).
Legitimate case to reinvent the wheel. I restored my deleted decorators that did dependency sanitation for me at runtime. The remaining piece of the puzzle was a recursive film iterator to feed the decorators. I checked my file system reader for clues on how to implement one and boom! The one I'd written for two other features was compatible. All I had to do was refactor decorators into dependency rules, give them fancy interfaces for customising and filtering what classes each rule should actually evaluate. In a night's work (if you're discrediting how long writing the original sanitization decorators and directory iterator), I coupled the Deptrac/phparkitect library of my dreams. This is one of the those few times I feel like a supreme deity
Hope I can eat better and get some sleep. This meme is me after getting bounced by those three library rejections -
#Suphle Rant 7: transphporm failure
In this issue, I'll be sharing observations about 3 topics.
First and most significant is that the brilliant SSR templating library I've eyed for so many years, even integrated as Suphle's presentation layer adapter, is virtually not functional. It only works for the trivial use case of outputting the value of a property in the dataset. For instance, when validation fails, preventing execution from reaching the controller, parsing fails without signifying what ordinance was being violated. I trim the stylesheet and it only works when outputting one of the values added by the validation handler. Meaning the missing keys it can't find from controller result is the culprit.
Even when I trimmed everything else for it to pass, the closing `</li>` tag seems to have been abducted.
I mail project owner explaining what I need his library for, no response. Chat one of the maintainers on Twitter, nothing. Since they have no forum, I find their Gitter chatroom, tag them and post my questions. Nothing. The only semblance of a documentation they have is the Github wiki. So, support is practically dead. Project last commit: 2020. It's disappointing that this is how my journey with them ends. There isn't even an alternative that shares the same philosophy. It's so sad to see how everybody is comfortable with PHP templating syntax and back end logic entagled within their markup.
Among all other templating libraries, Blade (which influenced my strong distaste for interspersing markup and PHP), seems to be the most popular. First admission: We're headed back to the Blade trenches, sadly.
2nd Topic: While writing tests yesterday, I had this weird feeling about something being off. I guess that's what code smell is. I was uncomfortable with the excessive amount of mocking wrappers I had to layer upon SUT before I can observe whether the HTML adapter receives expected markup file, when I can simply put a `var_dump` there. There's a black-box test for verifying the output but since the Transphporm headaches were causing it to fail, I tried going white-box. The mocking fixture was such a monstrosity, I imagined Sebastian Bergmann's ghost looking down in abhorrence over how much this Degenerate is perverting and butchering his creation.
I ultimately deleted the test travesty but it gave rise to the question of how properly designed system really is. Or, are certain things beyond testing white box? Are there still gaps in the testing knowledge of a supposed testing connoisseur? 2nd admission.
Lastly, randomly wanted to tweet an idea at Tomas Votruba. Visited his profile, only to see this https://twitter.com/PovilasKorop/.... Apparently, Laravel have implemented yet another feature previously only existing in Suphle (or at the libraries Arkitekt and Deptrac). I laughed mirthlessly as I watch them gain feature-parity under my nose, when Suphle is yet to be launched. I refuse to believe they're actually stalking Suphle2