Sessions is temporarily moving to YouTube, check out all our new videos here.

How to Create Maintainable Projects

Michael Koeppl speaking at FreeCodeCamp Vienna in September, 2017
Great talks, fired to your inbox 👌
No junk, no spam, just great talks. Unsubscribe any time.

About this talk

Watch how to write maintainable code. Michi will focus on the importance of comments and the structure of code statements.


I'm going to try to make it seem like I'm relaxed, which I'm not, so I'm going to talk about how to write maintainable code and how to stay sane when working with code, other people's code, your own code, and yeah. Because I'm sure many of you already know who are working in the industry, you're going to work with bad code, all the time. It's just a given. So yeah, I think this is a topic basically everyone is interested in, I hope. First of all, do we even know what I'm talking about, and I want to. You may be thinking I'm not a credible source because I'm young, basically, so I'm going to start with a little introduction on why I think I can talk and should talk about this topic. So I'm going to start by saying, okay let's make this a little interactive. Who can guess how old I am. - [Audience] Nine, 26, 16. - Okay, that's what most people think, so yeah I'm 20 years old. So I look a lot younger than I am, so yeah. I've been. Sorry. Okay. I've been coding for six years now. I started before I went to like a technical college. I've been studying software engineering for the past five years, and I've been working on many projects, of which most have terrible code, and yeah, I learned from that basically. And for the last two months I've been working at a big company in Vienna, and they had me start working on a very bad code base right away because the whole tool, it's a tool where employees answer questions. It doesn't sound very difficult. It's basically a simple task, but the whole code was scattered over many different files and they have no clear intent, these files, so it was, the code was everywhere, and it didn't show a clear intent. So yeah, I know what that does to you and I'm sure some of you know as well. So this is why I'm talking about this because it's really frustrating to work with bad and unmaintainable code. So let's start with the four pillars of maintainable code, or what I think they are. So it's expressive comments. We'll talk about each of them individually. Then the second one is naming or self documenting code, then the readability over elegance and conventions. Expressive comments, yeah. Code allows us to express our solutions to problems. So do you know that feeling when you code something and you already have the whole solution figured out in your head? Now I mentioned looking at someone else's code. Can you instantly see what they thought of when they wrote that? Can you see the intent instantly? Who knows, maybe they were drunk when they wrote it, you know. So that's why it's a good idea to describe what you thought, your thought process and why you decided to solve a problem this way. With expressive comments. So we've got, we've started with these comments, and I have a question for you, which is why do you think these comments are not useful? Anyone? Yeah, exactly. There's no need to state the obvious. So yeah, these comments are not very useful. What is useful, or can be useful, is not writing what it does, basically, if you don't have to, it's writing why you're doing it. That is a lot more important than what, so here I tried to describe the reason why the statement is there and why it's filtering for an A, basically. So it's a high level explanation of what you're doing and why. Also, avoids commenting every single line because you don't need to. Explain the parts that are hard to understand and try to avoid parts that are hard, try to avoid writing code that is hard to understand so you don't have to comment in the first place. Because at some point someone's going to read your code, probably, even if that is you in a few weeks or months or years, and yeah, you're not going to be able to understand it instantly. The next point is variable naming or general naming, or self documenting code. Because we can help or can try to make our code more understandable by not naming things stuff like A, B, C, or stuff like that, but giving them names that are meaningful, giving them names that tell us what a function is for, what it does, what the variable is for, and so on. So yeah, that's basically how you make the code self document itself. So the code basically communicates your intent without any additional comments. Who can tell me what this is? No one? Yeah, but what does it do, what is it for? Yeah, but what does it calculate, what is C? Okay, but my point is a bit different one. It's the area of a triangle. Did you know that from the first code, like is it instantly obvious? No it's not. It's just basic formula for the area of a triangle. So instantly the more descriptive names make it easier to understand, and I think we can agree on that. Okay, so it might even make sense to move that code to a separate function which describes what it does, which is what happened here. We calculated the triangle area and gave the parameters descriptive name as well, so it's not just A, B, and C and stuff, so it's something that lets you know what it is. Yeah the next point is a bit of a tricky one. Readability over elegance. Because there's nothing inherently wrong with elegance because you can write elegant code and it can make your codes, I don't know, run faster or, bless you. It can make your code run faster, it can just seem sexy to you, basically. But the thing is that's not always good because elegant code is also, or can be also, very difficult to read, understand, and maintain. And thinking of stuff like regex, regular expressions, and one liners, basically, where you solve a problem in one line with I don't know, in line if statements and operators and stuff like that, but the thing is, someone who didn't write it themselves but reads your code later on and tries to maintain it, they may not instantly know what it does or they may not be able to solve it this way. They may have to rewrite it later on with multiple statements, not as a one liner or as a regular expression, so elegance doesn't have to be wrong, but you shouldn't overdo it. Do it for things that stay readable if you try an elegant solution, but try to keep it simple, try to keep it descriptive in writing code, and yeah. Yeah, that's one of his examples. Basically you write a regular expression and yeah, no one can touch it because no one understands it anyway. I forgot the memes, yeah. Alright, so this is an example of something I wrote like two years ago in school. It's part of a programme that puts watermarks on images. What this thing does is it draws a diagonal line for a number, and I wouldn't be able to change anything about that anymore without like rewriting the code around that because I have no idea how this works or why. So that's kind of my point. This is an unnecessary one, like if I had split this up and been more descriptive about it and tried to describe my intent, then I wouldn't have this one liner and of course it's understandable, hopefully. Yeah, the last point is conventions. Conventions are something that many people think is not very important, but I believe it's important, especially if you work with other people on code. So this is basically about how you name your functions, how you name your variables, which naming styles you use, where you place your braces and stuff, which may not seem very important, but it gets really important if you start mixing different styles because it makes your code less structured, basically. It may be confusing to people using your code. That's part of what made the code base I'm currently working with terrible because some functions were named in snake case, which is you have underlines between the words and some were named with Pascal case and camel case, so you don't know what to search for, basically, because the functions all have different names. And it's just mixed, so. Examples, that's camel case for example. You start with a small letter, and then for each word you have a capital letter, basically. That's Pascal case, you start with a capital letter, and snake case. And then there's also the possibility of putting your braces on the next line or the same line, which may not seem very important, but it gets important if you work with a big code base and people start mixing that up and it's annoying, basically. And that's why most code bases that are open source and where many people contribute have guidelines, how to write code, how to write code that fits into their code base. So we'll get to that. That's kind of too long, didn't watch, didn't listen, of this talk. It's one of my favourite codes, basically. So yeah, that's what I try to do because I've written a lot of code over the past few years, and every time I look back on an old code, like something I wrote a year ago or two years ago, I wouldn't believe that I wrote that and I couldn't tell you, or wouldn't be able to tell you why I wrote it that way because usually I think it's horrible, basically. So yeah, that's the end of my presentation.