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 - "bad documentation"
-
I'm drunk and I'll probably regret this, but here's a drunken rank of things I've learned as an engineer for the past 10 years.
The best way I've advanced my career is by changing companies.
Technology stacks don't really matter because there are like 15 basic patterns of software engineering in my field that apply. I work in data so it's not going to be the same as webdev or embedded. But all fields have about 10-20 core principles and the tech stack is just trying to make those things easier, so don't fret overit.
There's a reason why people recommend job hunting. If I'm unsatisfied at a job, it's probably time to move on.
I've made some good, lifelong friends at companies I've worked with. I don't need to make that a requirement of every place I work. I've been perfectly happy working at places where I didn't form friendships with my coworkers and I've been unhappy at places where I made some great friends.
I've learned to be honest with my manager. Not too honest, but honest enough where I can be authentic at work. What's the worse that can happen? He fire me? I'll just pick up a new job in 2 weeks.
If I'm awaken at 2am from being on-call for more than once per quarter, then something is seriously wrong and I will either fix it or quit.
pour another glass
Qualities of a good manager share a lot of qualities of a good engineer.
When I first started, I was enamored with technology and programming and computer science. I'm over it.
Good code is code that can be understood by a junior engineer. Great code can be understood by a first year CS freshman. The best code is no code at all.
The most underrated skill to learn as an engineer is how to document. Fuck, someone please teach me how to write good documentation. Seriously, if there's any recommendations, I'd seriously pay for a course (like probably a lot of money, maybe 1k for a course if it guaranteed that I could write good docs.)
Related to above, writing good proposals for changes is a great skill.
Almost every holy war out there (vim vs emacs, mac vs linux, whatever) doesn't matter... except one. See below.
The older I get, the more I appreciate dynamic languages. Fuck, I said it. Fight me.
If I ever find myself thinking I'm the smartest person in the room, it's time to leave.
I don't know why full stack webdevs are paid so poorly. No really, they should be paid like half a mil a year just base salary. Fuck they have to understand both front end AND back end AND how different browsers work AND networking AND databases AND caching AND differences between web and mobile AND omg what the fuck there's another framework out there that companies want to use? Seriously, why are webdevs paid so little.
We should hire more interns, they're awesome. Those energetic little fucks with their ideas. Even better when they can question or criticize something. I love interns.
sip
Don't meet your heroes. I paid 5k to take a course by one of my heroes. He's a brilliant man, but at the end of it I realized that he's making it up as he goes along like the rest of us.
Tech stack matters. OK I just said tech stack doesn't matter, but hear me out. If you hear Python dev vs C++ dev, you think very different things, right? That's because certain tools are really good at certain jobs. If you're not sure what you want to do, just do Java. It's a shitty programming language that's good at almost everything.
The greatest programming language ever is lisp. I should learn lisp.
For beginners, the most lucrative programming language to learn is SQL. Fuck all other languages. If you know SQL and nothing else, you can make bank. Payroll specialtist? Maybe 50k. Payroll specialist who knows SQL? 90k. Average joe with organizational skills at big corp? $40k. Average joe with organization skills AND sql? Call yourself a PM and earn $150k.
Tests are important but TDD is a damn cult.
Cushy government jobs are not what they are cracked up to be, at least for early to mid-career engineers. Sure, $120k + bennies + pension sound great, but you'll be selling your soul to work on esoteric proprietary technology. Much respect to government workers but seriously there's a reason why the median age for engineers at those places is 50+. Advice does not apply to government contractors.
Third party recruiters are leeches. However, if you find a good one, seriously develop a good relationship with them. They can help bootstrap your career. How do you know if you have a good one? If they've been a third party recruiter for more than 3 years, they're probably bad. The good ones typically become recruiters are large companies.
Options are worthless or can make you a millionaire. They're probably worthless unless the headcount of engineering is more than 100. Then maybe they are worth something within this decade.
Work from home is the tits. But lack of whiteboarding sucks.39 -
In the darkest of days, I discovered how to remote login to my computer at work through the company vpn. I then proceeded to work overtime at night in secret for a week or so, writing documentation and refactoring code.
I finally woke the fuck up and realized that I shouldn't be obsessing over proprietary codebases that do not belong to me, and I should put this misguided energy into my own projects.
So yeah, as a bad dev habit I'm working on fixing, this fits the bill.4 -
Udemy courses are targeted at ABSOLUTE beginners. It's excruciating to pull through and finish the course "just because". And some of these courses are jam-packed with 30-60 hours just for them to appear legit, but the reality is the value you get could be packed to 3-5 hours.
You're better off just searching for or watching for the things that you need on Google or YouTube.
You'll learn more when building the actual stuff. Yes, it's good to go for the documentation. Just scratch the "Getting Started" section and then start building what you want to build already. Don't read the entire documentation from cover to cover for the sake of reading it. You won't retain everything anyway. Use it as a reference. You'll gain wisdom through tons of real-world experience. You will pick things up along the way.
Don't watch those tutorials with non-native English speakers or those with a bad accent as well. Native speakers explain things really well and deliver the message with clarity because they do what they do best: It's their language.
Trust me, I got caught up in this inefficient style a handful of times. Don't waste your time.rant mooc bootcamp coursera freecodecamp skillshare tutorial hell learning udacity udemy linkedin learning8 -
What an absolute fucking disaster of a day. Strap in, folks; it's time for a bumpy ride!
I got a whole hour of work done today. The first hour of my morning because I went to work a bit early. Then people started complaining about Jenkins jobs failing on that one Jenkins server our team has been wanting to decom for two years but management won't let us force people to move to new servers. It's a single server with over four thousand projects, some of which run massive data processing jobs that last DAYS. The server was originally set up by people who have since quit, of course, and left it behind for my team to adopt with zero documentation.
Anyway, the 500GB disk is 100% full. The memory (all 64GB of it) is fully consumed by stuck jobs. We can't track down large old files to delete because du chokes on the workspace folder with thousands of subfolders with no Ram to spare. We decide to basically take a hacksaw to it, deleting the workspace for every job not currently in progress. This of course fucked up some really poorly-designed pipelines that relied on workspaces persisting between jobs, so we had to deal with complaints about that as well.
So we get the Jenkins server up and running again just in time for AWS to have a major incident affecting EC2 instance provisioning in our primary region. People keep bugging me to fix it, I keep telling them that it's Amazon's problem to solve, they wait a few minutes and ask me to fix it again. Emails flying back and forth until that was done.
Lunch time already. But the fun isn't over yet!
I get back to my desk to find out that new hires or people who got new Mac laptops recently can't even install our toolchain, because management has started handing out M1 Macs without telling us and all our tools are compiled solely for x86_64. That took some troubleshooting to even figure out what the problem was because the only error people got from homebrew was that the formula was empty when it clearly wasn't.
After figuring out that problem (but not fully solving it yet), one team starts complaining to us about a Github problem because we manage the github org. Except it's not a github problem and I already knew this because they are a Problem Team that uses some technical authoring software with Git integration but they only have even the barest understanding of what Git actually does. Turns out it's a Git problem. An update for Git was pushed out recently that patches a big bad vulnerability and the way it was patched causes problems because they're using Git wrong (multiple users accessing the same local repo on a samba share). It's a huge vulnerability so my entire conversation with them went sort of like:
"Please don't."
"We have to."
"Fine, here's a workaround, this will allow arbitrary code execution by anyone with physical or virtual access to this computer that you have sitting in an unlocked office somewhere."
"How do I run a Git command I don't use Git."
So that dealt with, I start taking a look at our toolchain, trying to figure out if I can easily just cross-compile it to arm64 for the M1 macbooks or if it will be a more involved fix. And I find all kinds of horrendous shit left behind by the people who wrote the tools that, naturally, they left for us to adopt when they quit over a year ago. I'm talking entire functions in a tool used by hundreds of people that were put in as a joke, poorly documented functions I am still trying to puzzle out, and exactly zero comments in the code and abbreviated function names like "gars", "snh", and "jgajawwawstai".
While I'm looking into that, the person from our team who is responsible for incident communication finally gets the AWS EC2 provisioning issue reported to IT Operations, who sent out an alert to affected users that should have gone out hours earlier.
Meanwhile, according to the health dashboard in AWS, the issue had already been resolved three hours before the communication went out and the ticket remains open at this moment, as far as I know.5 -
This happened today...
Manager: how long this is going to take?
Dev: 3 months
M: cool! 3 weeks then
D: no.. This is quite complicated and most of us are unfamiliar with the topics. It'll take us 2 weeks just to get started
M: drop the unit tests then. Just get the features done in 3 weeks. We have customers waiting
D: that's a bad idea. We'll end up with unstable co..
M: oh we also need to complete documentation, release guide, and this [shitty feature no one care about]
D: but that is even more complex. We don't have enough ti..
M: just copy it from stackoverflow. It'll only take 5 minutes guys
Worst part? This guy is technically sound and understands our pain really well. He is just acting dumb and trying to put the blame on us when the higher management asks
Second worst part? The whole team keeps silent when I try to convince him somehow and starts ranting after he leaves the call2 -
What the fuck is wrong with web designers these days?
Every fucking web page is white with black text. It's 2022, let's stop this paper bullshit and change everything to use colors that make sense on screens.
For fuck sakes, even monokai.pro is black on white. You know monokai, that dark colorful color scheme that most editors support. With a black background and white text.
I'm nursing the worst migraine in the world right now and all I want to do is smash people's faces into these shitty white screens.
It wouldn't be so bad if these fuckers would have a dark mode, but 80% of the documentation that I have to read doesn't support dark mode. Yeah I know about the browser plugins that do it for you, but I honestly don't trust any of them since most of them have been found to be spyware.13 -
This would be my first official post.
Been a IT Technician for a managed service provider for the past 9 years up until last year August. Managing director pulls me in with a movement to App Development after coming across some personal hobby projects I have done in the past.
Started in the new position in November as Junior Developer and workloads get dumped on me and left to figure it out. 4 weeks of running through code without documentation and the solutions started to make sense.
Started a new solution for a Large remote customer with documentation and timelines in December and I get pulled in again for a second time in front of the MD.
Good News:With effect in January I have been promoted to Head of Application development.
Bad News: The existing department head is leaving end of the month and I am to go 900km from home to hand over all responsibilities for the next 3 weeks.
Better News: Department has started shifting to DevOps and it is up to me to set the policies and work flows to how I see fit.
Worse news: it starts by expanding the team asap as 10 projects accounting to 4000 man hours with deadlines in Q3.
Wish me luck. It's going to be twisted Rollercoaster ride...5 -
I hate React. I keep reading that people have problem of grasping it, but that's not the case for me. I get it, I understand it, but I hate with passion HOW it's done knowing how nice it's done elsewhere. What really triggers me is how ugly it looks, both from architecture and code level. To me it really say a lot when even code shown in documentation looks ugly, and while reading it you ask ourself constantly "why it's done this way?". When I read React being called an "elegant" solution something explodes in me. Did you saw Svelte? Vue? Damn, even Alpine.js?
I just cannot how overengineered this API is. Even doing simplest things there produces so much junk code written only because this is what library requires. Why? I feel like working with it is a punishment.
And scalability and maintainability? I've never seen large-scale projects more messed up than those wrote with React. And yes, you can blame teams working on them for lack of skills, but it is the library which encourages or not good practices also, and I've never seen such bad situation with other libraries/frameworks.8 -
So, I've had a personal project going for a couple of years now. It's one of those "I think this could be the billion-dollar idea" things. But I suffer from the typical "it's not PERFECT, so let's start again!" mentality, and the "hmm, I'm not sure I like that technology choice, so let's start again!" mentality.
Or, at least, I DID until 3-4 months ago.
I made the decision that I was going to charge ahead with it even if I started having second thoughts along the way. But, at the same time, I made the decision that I was going to rely on as little external technology as possible. Simplicity was going to be the key guiding light and if I couldn't truly justify bringing a given technology into the mix, it'd stay out.
That means that when I built the front end, I would go with plain HTML/CSS/JS... you know, just like I did 20+ years ago... and when I built the back end, I'd minimize the libraries I used as much as possible (though I allowed myself a bit more flexibility on the back end because that seems to be where there's less issues generally). Similarly, any choice I made I wanted to have little to no additional tooling required.
So, given this is a webapp with a Node back-end, I had some decisions to make.
On the back end, I decided to go with Express. Previously, I had written all the server code myself from "first principles", so I effectively built my own version of Express in other words. And you know what? It worked fine! It wasn't particularly hard, the code wasn't especially bad, and it worked. So, I considered re-using that code from the previous iteration, but I ultimately decided that Express brings enough value - more specifically all the middleware available for it - to justify going with it. I also stuck with NeDB for my data storage needs since that was aces all along (though I did switch to nedb-promises instead of writing my own async/await wrapper around it as I had previously done).
What I DIDN'T do though is go with TypeScript. In previous versions, I had. And, hey, it worked fine. TS of course brings some value, but having to have a compile step in it goes against my "as little additional tooling as possible" mantra, and the value it brings I find to be dubious when there's just one developer. As it stands, my "tooling" amounts to a few very simple JS scripts run with NPM. It's very simple, and that was my big goal: simplicity.
On the front end, I of course had to choose a framework first. React is fine, Angular is horrid, Vue, Svelte, others are okay. But I didn't want to bother with any of that because I dislike the level of abstraction they bring. But I also didn't want to be building my own widget library. I've done that before and it takes a lot of time and effort to do it well. So, after looking at many different options, I settled on Webix. I'm a fan of that library because it has a JS-centric approach. There's no JSX-like intermediate format, no build step involved, it's just straight, simple JS, and it's powerful and looks pretty good. Perfect for my needs. For one specific capability I did allow myself to bring in AnimeJS and ThreeJS. That's it though, no other dependencies (well, at first, I was using Axios because it was comfortable, but I've since migrated to plain old fetch). And no Webpack, no bundling at all, in fact. I dynamically load resources, which effectively is code-splitting, and I have some NPM scripts to do minification for a production build, but otherwise the code that runs in the browser is what I actually wrote, unlike using a framework.
So, what's the point of this whole rant?
The point is that I've made more progress in these last few months than I did the previous several years, and the experience has been SO much better!
All the tools and dependencies we tend to use these days, by and large, I think get in the way. Oh, to be sure, they have their own benefits, I'm not denying that... but I'm not at all convinced those benefits outweighs the time lost configuring this tool or that, fixing breakages caused by dependency updates, dealing with obtuse errors spit out by code I didn't write, going from the code in the browser to the actual source code to get anywhere when debugging, parsing crappy documentation, and just generally having the project be so much more complex and difficult to reason about. It's cognitive overload.
I've been doing this professionaly for a LONG time, I've seen so many fads come and go. The one thing I think we've lost along the way is the idea that simplicity leads to the best outcomes, and simplicity doesn't automatically mean you write less code, doesn't mean you cede responsibility for various things to third parties. Those things aren't automatically bad, but they CAN be, and I think more than we realize. We get wrapped up in "what everyone else is doing", we don't stop to question the "best practices", we just blindly follow.
I'm done with that, and my project is better for it! -
Documentation is like sex:
When it's good, it's very good.
When it's bad, it's better than nothing...4 -
Holy shiiittttt I finally got 64bit NASM working on windows with cmake. Cmake documentation is fkn bad man.
I’ve got a c++ file that calls a procedure in an assembly file that calls win32 APIs to show dialogs and other cool shit. Compiling was working fine, linking turned out to be a bit of a pain in the ass, but figuring out how to enable NASM in cmake was a nightmare. Why is the cmake docs so horrific 🥺1 -
My best and worst dev experience this year was getting a new job.
The bad parts: I’m inheriting a code base that was maintained by an outside agency, so there’s very little documentation. There’s a lot of systems maintenance and upgrades that have to be done because it was never done. I’m working at a larger organization, so tracking down who I need for info can be tricky. I’m the only person maintaining my code base.
Now the good parts: Better pay and benefits. My co workers, dev and non-dev, are always helpful. Since the dev team is small, we are very discerning when we pick up work for the websites. I have more independence to self-learn. I’m not at a blame culture. My role is permanently remote.
So far I think the good outweighs the bad.2 -
When the CTO/CEO of your "startup" is always AFK and it takes weeks to get anything approved by them (or even secure a meeting with them) and they have almost-exclusive access to production and the admin account for all third party services.
Want to create a new messaging channel? Too bad! What about a new repository for that cool idea you had, or that new microservice you're expected to build. Expect to be blocked for at least a week.
When they also hold themselves solely responsible for security and operations, they've built their own proprietary framework that handles all the authentication, database models and microservice communications.
Speaking of which, there's more than six microservices per developer!
Oh there's a bug or limitation in the framework? Too bad. It's a black box that nobody else in the company can touch. Good luck with the two week lead time on getting anything changed there. Oh and there's no dedicated issue tracker. Have you heard of email?
When the systems and processes in place were designed for "consistency" and "scalability" in mind you can be certain that everything is consistently broken at scale. Each microservice offers:
1. Anemic & non-idempotent CRUD APIs (Can't believe it's not a Database Table™) because the consumer should do all the work.
2. Race Conditions, because transactions are "not portable" (but not to worry, all the code is written as if it were running single threaded on a single machine).
3. Fault Intolerance, just a single failure in a chain of layered microservice calls will leave the requested operation in a partially applied and corrupted state. Ger ready for manual intervention.
4. Completely Redundant Documentation, our web documentation is automatically generated and is always of the form //[FieldName] of the [ObjectName].
5. Happy Path Support, only the intended use cases and fields work, we added a bunch of others because YouAreGoingToNeedIt™ but it won't work when you do need it. The only record of this happy path is the code itself.
Consider this, you're been building a new microservice, you've carefully followed all the unwritten highly specific technical implementation standards enforced by the CTO/CEO (that your aware of). You've decided to write some unit tests, well um.. didn't you know? There's nothing scalable and consistent about running the system locally! That's not built-in to the framework. So just use curl to test your service whilst it is deployed or connected to the development environment. Then you can open a PR and once it has been approved it will be included in the next full deployment (at least a week later).
Most new 'services' feel like the are about one to five days of writing straightforward code followed by weeks to months of integration hell, testing and blocked dependencies.
When confronted/advised about these issues the response from the CTO/CEO
varies:
(A) "yes but it's an edge case, the cloud is highly available and reliable, our software doesn't crash frequently".
(B) "yes, that's why I'm thinking about adding [idempotency] to the framework to address that when I'm not so busy" two weeks go by...
(C) "yes, but we are still doing better than all of our competitors".
(D) "oh, but you can just [highly specific sequence of undocumented steps, that probably won't work when you try it].
(E) "yes, let's setup a meeting to go through this in more detail" *doesn't show up to the meeting*.
(F) "oh, but our customers are really happy with our level of [Documentation]".
Sometimes it can feel like a bit of a cult, as all of the project managers (and some of the developers) see the CTO/CEO as a sort of 'programming god' because they are never blocked on anything they work on, they're able to bypass all the limitations and obstacles they've placed in front of the 'ordinary' developers.
There's been several instances where the CTO/CEO will suddenly make widespread changes to the codebase (to enforce some 'standard') without having to go through the same review process as everybody else, these changes will usually break something like the automatic build process or something in the dev environment and its up to the developers to pick up the pieces. I think developers find it intimidating to identify issues in the CTO/CEO's code because it's implicitly defined due to their status as the "gold standard".
It's certainly frustrating but I hope this story serves as a bit of a foil to those who wish they had a more technical CTO/CEO in their organisation. Does anybody else have a similar experience or is this situation an absolute one of a kind?2 -
I feel super discouraged. I just got a new job from being let go from my previous one, and I’m already thinking about quitting.
They really threw me into the weeds with a couple of complex tasks that require a lot of BE work and all I really do is FE. I’m still just trying to learn how the framework actually works. I think they expect me to become full stack. Now I find myself just starting at the computer screen most of the day because I have no fucking idea how to start working. The codebase and local environment is also fucked up super bad and barely runs on my machine.
Also, whenever I reach out these people they give the most minimal answers and have swollen egos. The frameworks they use have a really shitty community and bad documentation, so googling anything is really pointless. Working on this project, it has made me consider giving up development.
I am wondering if this is just a me thing though. Should I quit or stick with it for a bit?13 -
Today, I started a new project with Rails. I used always an own auth implementation, now I thought I'll give devise a try. Hell... the documentation is bad, really really bad. I really don't know why people are using this and don't write this by themselves. Anyway, I kicked devise and write it again by myself.8
-
I am currently trying to set up a unit-test using Python Django framework.
I follow the official documentation step by step. I completed the steps.
It spits out an error: the table does not exist in the database.
Seriously, do you need any more proof that Python is bad? The developers of Python framework cannot even put together a working tutorial. If the unit-test framework requires the database then it should auto-create the tables3 -
#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