Interesting point, and I'm 100% pro good documentation. However, as an old coder, I know that this problem was solved a long time ago with Classes. If these vague raw objects were instances of "User" with a method called "isAdmin" and no public "admin boolean" then, boom, no problemo! The main issue is that it's trending to vilanize OOP so people are reinventing the wheel with what they think is functional programming.
100% with you. abstraction and proper encapsulation are key to speed up and better soft dev. from my experience most code bases are low quality and most devs don't know/don't care to make it better. it's exactly like you said. you can write some classes with proper methods and sweet encapsulation but they don't even look at it or care to understand it (they want it "lazy"). they raise PRs accessing object properties directly (for example)....it's imediate reject from me.
Cool video! Documentation is important, but one of the big challenges is balancing it with tight deadlines... Clients often push for fast feature delivery, making it tough to dedicate time to proper documentation... The pressure to ship products fast sometimes pushes documentation down the priority list..
At the same time, for a large project with multiple developers you would probably deliver features faster if you had a culture of documentation since then you wouldn’t have to grep through large parts of could someone else wrote for multiple hours just to understand one function or class.
There will always be conflict between devs and business management where devs want to do things "right" and be mindful of what will be effective, maintainable, and stable in the long run, and business management wants to do things "fast" with some level of risk tolerance because that's what will make the business competitive, and only the creation of value to the user can justify the business's revenue. Both sides have valid points. Unfortunately, management often eventually runs into worse profits as a result of previous decisions to move too quickly. The case I guess I'm trying to make in this video is that it's worth it to allow devs time to document sufficiently, just like some companies allow devs time to write comprehensive unit tests.
Brilliant video. Thanks. I wish someone could tell me what I can do, I have an issue related to the video topic: We have lots of repos, and there's only my boss (the principal engineer) who understand how everything works. The code has grown a lot and there's zero code documentation, I am requested to write features without going out of the standard for how x, y or z has already been implemented in the code elsewhere from the module I'm working in. This results in him requesting me to rewrite entire feature branches several times until it follows how everything else works (I'm dedicated and would've written them propperly if I could've accessed those details beforehand). The business is fairly complicated, therefore the code also becomes complex due to a minimum complexity threshold. But if I ask the guy for details (because he IS the documentation) he's always going to have oversights that result in me redoing my work afterwards. My question: Is this a skill issue on my end? Should I be able to read the code better, open up myself more to the mess in the current code? What can I do to polish up a bit? I don't know what to do about it, is it normal to be requested to rewrite something 3, 4 different times? (I understand what I am doing in my code at least a bit, it's not always that my code is a mess but rather that it goes outside of the standard for how something else is written somewhere unknown to me). Is my perspective wrong? Thanks.
There is a skill to deciphering legacy code bases in order to "get along" with how they already do things, but it's a skill that your boss shouldn't have to expect everyone to be able to do to even be able to work. Unfortunately this is the case in many places because they haven't experienced the velocity improvement that comes from having clear documentation. I don't think it's your fault, but I do think in your case you'll have to just do your best to read through and understand what's available for you to use. One example is I've had to implement new api endpoints for a project that has an existing repo for the back end. Adding a new endpoint involves modifying at least three different files in very specific ways, following the pattern the existing endpoints are using. I've definitely missed changes I was supposed to make because it wasn't clear to me I had to make them because nothing was documented. So I'd recommend always trying to find whether there's an established pattern/methodology for doing something before beginning to implement something. There might not be, but it can't hurt to ask "Hey, when you guys need to write to the database, do you just call the dependency's methods directly, or is there a helper class I can use?". The more you work in big legacy code bases, the more people you're gonna have to talk to. The complexity might even warrant a phone call or face-to-face meeting to really get it.
Wow dude this video couldn't have come at a better time for me. I had the opinion that you shot down in the first 30 seconds, and realized that I was saying that pointers in C are too much of an abstraction because they didn't make sense to me and were "simpler" to me in assembly (and supposedly therefore better). Thank you!
It's were optimistic to expect devs who don't even care to understand your abstraction to actually search, read and keep up to date some external documentation.
Very nice presentation. Problem is I've never seen a programmer want to or think about reading documentation for a class and its methods like this. Even if they do there is little faith in that the documentation has been maintained. I think the ideal is to have code that is readable and maintainable, i.e., code that documents itself. Anything beyond the usual "abstraction" might get ignored... unless they have to deal with it like it being part of a library that is pulled in everywhere.
If the code documents itself so well that all the contributors decide to use the abstractions that are already present, then that's awesome. And to a certain point of complexity, I think that's exactly what you want. I do also think projects can become so large and feature sets can become so complex that it's infeasible the code could be reasonably expected to document itself sufficiently. When you use a framework (Laravel, for example), when you approach a new problem your instinct is to go to the docs and see whether they have a built-in way to do it, and that's a consequence of having excellent documentation, IMO.
Remember abstraction works in levels, so we have db lvl repo lvl domain lvl http lvl, dont mix them. This will help You to decide what to abstract and what not to.
I prefer using OOP because simply scattering functions across files increases the risk of duplication. Someone might rewrite existing code because they couldn’t easily find the relevant functions or tools. By organizing functionality into classes, you group related methods logically, making it easier to locate, understand, and extend the code.
You can run across this same issue with OOP because someone might not notice a certain class already exists, or might think the logic is simple enough it doesn't warrant reading through the class or trying to learn how it works, and they'll reimplement. If the project is simple enough, it might be clear what's there and how to use it without needing much documentation. On larger projects though, this issue crops up a lot, even with OOP. I'd like to do a video on functional programming versus OOP and give examples on how you might approach the same feature in both ways.
That's a really nice video. Can you also make some video about create that documentation? I'm not a developer but I'm working with infrastructure as a code and frequently I see terraform gymnastics or docker images writen in complicated way, even bash and python scripts are hard to understand. The knowledge is very distributed and mixed
I've actually just been thinking about this same issue recently - we, as a community, keep talking about avoiding unecessary complexity, avoiding over-abstraction, code should be really easy to read, etc. We even make this disctintion between accidental vs essential complexity, where essential complexity is related to the domain, and accidental complexity is everything else and is inherently bad. And I feel like, as a culture, we've been pushing this abstraction-avoidance thing too far. Of course, any abstractions we create if fine, because we see the obvious benefit to them, but anytime we run into an abstraction someone else made that we don't immedietally click, well, that was obviously a bad abstraction - it was far too complicated, someone ought to refactor that. And as a result of this mindset, we're producing this rewrite culture, where we're having to constantly rewrite codebases from one set of abstractions to another set of abstractions we prefer. Better documentation might help, I agree. But I also think that, more fundamentally, we also just need to have a shift in our culture. We shouldn't be so afraid of complexity. We should be willing to be more patient when trying to understand code other people have written, and try to be more understanding and respectful of their choices. We should try working within their abstractions to the best we can for a while and try to understand their perspective before we go about up-ending everything. Maybe we'd even learn a thing or two by trying to try out someone else's way of thinking. And, ya know, sometimes the code really is rotten because it is unecessarily abstracted or underabstracted, and it really does need to be upended. Or maybe parts of it could be revisted, but the overall idea was fine - perhaps not what you would have picked, but it's fine. So not saying we shouldn't touch the abstractions other people have made, just that we, perhaps, need to be more thoughtful before we touch them.
leaky abstractions are the problem. when the abstraction makes it so I can't get the same performance as without it, that is a leak. I need to think under the covers of the abstraction. when the abstraction makes it harder to actually do what I'm trying to do, that's a leak. I need to think under the covers of the abstraction. even well thought abstractions have a cost, if at least during maintenance and in the face of (perpetual) requirements changes. and people often aren't taught how to recognize or make decisions regarding those costs. many people are taught to always maximally abstract in every place they can think to abstract. and most of those abstractions have a big cost with little or negative value. DRY is a metric that is a proxy for code quality. and once people focus on optimizing for a metric that's a proxy, it stops being that useful a metric. damn right I'm going to use abstractions. sparingly. when they make sense, and obviously solve many more problems than they cause. when they don't take forever to come up with. when I don't paint myself into a corner of design with them. and it will usually take me a while to figure out the drawbacks of whatever abstraction I make, so I'm prone to only put them in when I've already suffered a decent amount of pain without them.
I think the main idea here is to make everyone wary of abstractions. Abstractions are a great tool of solving problems of the same kind but for different entities, but it has to be used with caution. The problem is that people try and find the one size fits all solution, like the do with hash maps and interview. People tend to do things they read or heard some smarter person say, without actually understanding what they said, they just repeat, leading to code that has abstractions where it should not have.
