No Compromises | Making a case for consistency

We see a lot of different projects, but it's pretty rare to find one that's well-documented and internally consistent. Why does that matter? And how can you make things more consistent without spending a lot of time on it?

(00:00) - We like keeping things tidy in our projects
(01:20) - Have a README, please
(03:30) - Is there a business case for consistency across projects?
(05:30) - An example with Docker build speeds in CI
(06:50) - Consistency in naming business concepts
(09:45) - Silly bit

Short, practical Laravel tips delivered fresh to your inbox. Sign up today!

Creators & Guests

Host

Aaron Saray

Host

Joel Clermont

What is No Compromises?

Two seasoned salty programming veterans talk best practices based on years of working with Laravel SaaS teams.

Joel Clermont (00:00):
Welcome to No Compromises, a peek into the mind of two old web devs who have seen some things. This is Joel.

Aaron Saray (00:08):
And this is Aaron.

Joel Clermont (00:16):
We have the privilege of seeing a lot of different code bases over time. We join projects and help them out and sometimes move on. I don't know, it's given me an appreciation, I think, for the projects maybe we start or that we've been in for years where we've kind of guided them just the way we like it. The way tools are set up and the way the README is organized. But it just made me think of this whole concept of sort of keeping things tidy. You can apply that at a few different layers that we might talk about here today. But have you experienced this, Aaron? You feel the same way as me, right? Jumping between projects where this tool is in a different spot and it works a slightly different way. I just can't, it's friction.

Aaron Saray (01:02):
Well, first of all when you say the README and stuff, that's a first of all, that's a pet peeve of mine. Like, if you're not going to update your README then delete it.

Joel Clermont (01:11):
Okay. Not the default Laravel README, you don't like seeing that when you open up project for the first time?

Aaron Saray (01:17):
Yeah, and that's already silly. But also, when the first set of things that you have in there and then maybe it's a solo dev that's been working on it for three or four years and they've moved on. Which is great, but they haven't updated documentation. Like, you know what? Everyone gets hit by buses, man, or whatever, you need to make sure that you can take over. But I get what you're saying, having stuff uniform. I think though based off what you just said, if we're going into a lot of different projects with a lot of different people, a lot of different standards, it's kind of hard to expect that things would be in the same place.

Joel Clermont (01:52):
Well, everybody should follow our way of doing it. In a perfect world. If we were joining a project for a month or two, I wouldn't expect them, "All right, you need to change. Like, everything's got to be set up with Docker Compose this way and here's how your composer scripts are organized." But I'm talking about things where we're in it for a while. And I've even seen this too, where we'll join a company, their team, and maybe they themselves have more than one project but the two are very different. Even within a team Project A, well, that's a little older and it does things this way. And then Project B is the newer one and it does things maybe a slightly better way. It annoys me. I mean, I'll admit part of this is on my mind because I've actually been going through several of our projects and looking for those differences. Because we do keep it up, I'd say it's like 95% of the way there. But every once in a while, you bump into a problem on a project and you solve it, but you don't then apply that solution to other projects where it would benefit them. I'm sort of normalizing these things and it's been on my mind and it's like, "Wow. Are we weird that we do this?" Or like, "Why don't more people do it?"

Aaron Saray (03:08):
When you talk about the team one, I'm going to play the Aaron's advocate here and say if we have an older project and a newer project and they're both relatively the same stack of tools and whatnot.

Joel Clermont (03:26):
Yeah, they're both Laravel.

Aaron Saray (03:26):
You starting to do stuff... doing stuff differently in the new one. What's the business case for spending time on the old one? Upgrading it or changing that stuff when I'm getting no new features from that set of tasks for the customers who are paying money?

Joel Clermont (03:42):
I mean, I would say that whether the team admits it or not, there's friction. Starting up a project this way versus that way, there is a little bit of context shifting going between them. You're going to have that anyways with different code bases, but I'm just saying I think there is maybe not a super tangible measurable benefit, but I think there is a benefit in having things be uniform.

Aaron Saray (04:07):
Yeah. I want to take it in a different direction. As an evil dev manager, let's just say, I don't care if you're unhappy or there's a little friction. I mean, I don't want you to be angry but like, "Oh, well, it's more difficult to work in this old application." Well, sorry, but that old application's what's built our company, giving us money to hire you so eat it. But I think you hit on a little bit on there, the difference between getting them running or more so the idea that it's difficult to share new concepts between two very disparate things. That's kind of what I would focus on instead and say, you're investing in us to learn new things on new Project X. We can add the value of that to Y if we start to bring these closer and closer together. Now, that doesn't mean that we stop for like two weeks and just do that.

Joel Clermont (04:57):
No.

Aaron Saray (04:57):
But you mix in that sort of stuff and say like, "With every single task moving forward, we're kind of going to mix in one of the 10 steps to bring this up to current then." Because I want to make sure it's clear that people understand when we say stuff too. Like, "You should bring these current," that doesn't mean stopping what you're doing and making a project... bringing it to current.

Joel Clermont (05:14):
No, and that's an important bit of detail. This isn't like a month-long project. Ideally, you'd be taking these little baby steps all along but even if you built up a backlog of these differences, well then you can still just solve them a little bit here and there. I want to give a tangible example because I think it might help because it's been a little abstract up to this point. But your tip on knowledge sharing, if you will, or lessons learned sparked this. Because we use Docker for local development, we also use Docker in our CI pipelines and it's one of the slowest things in the pipeline. To build the docker image and do this, and do that. So recently, I think you had shared an article with me and kind of challenged me like, "Hey, try this article and see if it makes our pipelines faster." And it took me a few attempts but we figured it out. Using some Docker tools to kind of cache those images locally, to not have to bring in external infrastructure, to do it all within the pipeline. But because our projects all use Docker in very similar ways, I can now go take what I learned there and shave a couple of minutes off all of our pipelines just by applying a few steps in the GitHub workflow action. Like, if they're all wildly different I'd have to kind of solve that in somewhat unique ways for each project, which would take longer. Or, I might just not do it at that point.

Aaron Saray (06:41):
I think you also hit on a really incredibly important topic, which is you don't always have to do this all the time. Sometimes you just challenge someone else in your team to do it and then they do the work for you. No, I totally agree with you. When you say you're upgrading these things and you develop something and you can kind of apply that one step. But I think there's other things too when it comes to maybe the business needs start to change so you might have situations where you used to... Or you didn't really even know the name of a thing so you built something, let's just say it's called a percentage or whatever, and then turns out that they call those a commission take. But when you look at your code it's all percentage models and that, this and stuff. When you're explaining to a new person or even yourself, you have to keep in mind, "Okay, when the business writes a new requirement or something..." And I'm being silly, writes a requirement, "when they tell me a new requirement-

Joel Clermont (07:40):
When they email you at 3:00 AM.

Aaron Saray (07:44):
Yeah. And they say, "Make the takes different." You have to go like, "Oh, that means the percentage model and change this and that."

Joel Clermont (07:52):
Yeah, that whole translation layer. And this is great because in the code you're saying the models are named one thing but then the user interface labels are probably named the business thing. Whenever it changed or became apparent there was a mismatch, you fixed that so that it doesn't agitate the users. But now as a developer, you have to constantly make that translation and you can't search for things using normal pattern matching and stuff like that. Yeah, that's another one that's front of mind for me right now too.

Aaron Saray (08:22):
It's definitely hard, like I said, if you're in the same project. It's far worse if you say, "Hey, I want to bring in consultants like us," and say, "Hey, we're going to bring you in for one month. Give us the best you can in this month." And we're like, "Well, first of all, what does percent mean?" And you're like, "Oh, well, that means this." It's like, "Okay. Well, did you put that in your README?" I bet you didn't.

Joel Clermont (08:45):
No. I'm trying to think, I don't think we've ever inherited a project that had a good README, that talked about business concepts and things like that. I don't think it's happened.

Aaron Saray (08:56):
I mean, well, sometimes you can put those in the Wiki too but just in general.

Joel Clermont (08:59):
Sure.

Aaron Saray (09:00):
I mean, I've worked with some teams that have a bunch of stuff in Confluence, things like that. But then the challenge there is those things get out of date and no one... They don't make that part of the process to update those as the code changes.

Joel Clermont (09:16):
Or even how do you discover it, right? Like, I'm in the code, I'm going to be searching the code, like, "Oh, you have this other tool. It's not where we host our code, it's not in the code but it's like this other thing you have to know how to go get access to that and search that." Documentation probably could be its own whole separate episode but even just that thing about naming. That's a huge one and it kind of ties into this theme nicely about keeping things tidy because that's a huge point of friction and I felt that recently too.

Aaron Saray (09:50):
Have you ever seen shows like MTV's Cribs or anything like that?

Joel Clermont (09:54):
Of course.

Aaron Saray (09:55):
So, I was thinking about those the other day and I'm like, "Well, when they show a house on there you know that it's a rich house."

Joel Clermont (10:00):
Right.

Aaron Saray (10:00):
Well, how do I know that a house is rich or it's fancy or whatever? I came up with two different measurements. I'm curious if you have any other ones that we can add into this.

Joel Clermont (10:10):
Okay.

Aaron Saray (10:10):
The first is if your house has a stairway but at the top of the stairway, you can go more than one direction, you have a rich house.

Joel Clermont (10:21):
Okay. I was thinking something different but, yeah, I like that. I was thinking when you walk into the house if there's a big room that just has a stairway in it. Like, that right away that's kind of upper class there. But, yeah, if you can go multiple directions. Okay, my house does not classic- There's only one way you can go. I'm failing the first one.

Aaron Saray (10:41):
Okay. Then second one is if the bathroom in the house is the same temperature as the rest of the house all the time.

Joel Clermont (10:53):
Okay. Can you be more specific about this?

Aaron Saray (10:55):
I can.

Joel Clermont (10:56):
Like, the air temperature or?

Aaron Saray (10:57):
Yeah. Because if you think about it, and probably in your house and mine, the bathroom is only two temperatures ever and it's never a good temperature. It's either really warm and kind of moist. Like, if there's a shower and you're just like, "Oh, I got to turn on the thing, get the air out of here."

Joel Clermont (11:12):
Sure, yeah.

Aaron Saray (11:12):
Or for some reason, indisputably, it's just cold as heck.

Joel Clermont (11:17):
Well, I can tell you why.

Aaron Saray (11:18):
And you walk and you're like, "Why is this room colder than everything else?" It's either really cold or really hot.

Joel Clermont (11:22):
In my house the reason it's cold is because someone took a shower, it was really hot and then they opened the window all the way and left it open. And I come up four hours later and it's winter and it's like, "Why is it freezing in here?" but yes.

Aaron Saray (11:36):
Well, yeah, if your bathroom is the same temperature as the rest of your house, even if someone took a shower or whatever, means it's huge probably, means that you are in a very upscale house.

Joel Clermont (11:45):
So, it's the size of the bathroom that allows it to be more at equilibrium with the house.

Aaron Saray (11:50):
Well, I guess. Yes, probably.

Joel Clermont (11:52):
Okay. Because I was thinking about floor temperature. Like we do, in our upstairs bathroom have heated floors and that is nice. I'm not going to lie.

Aaron Saray (12:00):
All right. So that's my third option. If you have heated floors in your house anywhere, you might be a rich Joel.

Joel Clermont (12:06):
Just one and it's like a tiny bathroom so it was cheap to put in.

Aaron Saray (12:10):
Any ideas that you have for rich houses? What's the measurement of rich?

Joel Clermont (12:14):
So, for me when you posed this question, honestly stairway is the first one that popped up. But the second one I was thinking is, how many garages do you have? Because if you can park like four cars, I don't know, to me that's like it's got to be a rich house because you have four cars. But, yeah, from the outside you can see that it's like, "Oh, that's a pretty fancy house."

Aaron Saray (12:38):
Yeah. Or the separate set of garages where it's like the two that are attached and then there's... you go a little...Oh yeah, if you have a turnaround. Like, if you go up your driveway and then you can spin around a fountain.

Joel Clermont (12:50):
A fountain?

Aaron Saray (12:51):
Yeah.

Joel Clermont (12:51):
If you got a fountain that's counting for sure.

Aaron Saray (12:54):
Man, I want a fountain.
Hey, maybe you're like me and you don't use Twitter that much, so you're not just following new things and new ideas and tips online, maybe you want that in your email. How would I ever get that, Joel?

Joel Clermont (13:09):
Well, you just head on over to masteringlaravel.io and that shiny newsletter signup form is right at the top of the page.