DEV Community: Jephte Colin

How clean is your code? Part I

Jephte Colin — Wed, 18 Nov 2020 18:02:38 +0000

Clean code? What does that even mean? Should I care as long as the code is working? The client won’t even see it 😏. How clean is really clean code?🤔

“I like my code to be elegant and efficient. The logic should be straightforward to make it hard for bugs to hide, the dependencies minimal to ease maintenance, error handling complete according to an articulated strategy, and performance close to optimal so as not to tempt people to make the code messy with unprincipled optimizations. Clean code does one thing well.”

-Bjarne Stroustrup, inventor of C++

This definition can be quite vague for a novice, but more or less clear for someone who is already writing clean code. This article will teach you a few important things on how to write clean code while keeping a good pace.

Why should you care about your code?

“C’est au pied du mur qu’on voit le maçon”, means that you’re are being evaluated based on your craft. When you’re applying for a job, someone will likely review your past project code, and what will they look for? They don’t have time to fully review your code, so they will look for mistakes(anti-pattern, code smells, bad naming). Very bad code = Not getting hired!

There’s that theory called the
Broken Windows Theory https://en.wikipedia.org/wiki/Broken_windows_theory that states: “… visible signs of crime, anti-social behavior, and civil disorder create an urban environment that encourages further crime and disorder, including serious crimes”. As the code is already bad, you tend to add more bad code. The truth is: “bad code scale very badly”.

As your codebase grows so does the number of bad code, it’s like cancer or gangrene, and you will likely end up in a situation where your code start hitting real hard on performance, have to change a lot of code just to implement a feature, take you a long time to make changes because it takes you more time to figure out what the code does, or it simply can’t scale anymore!

Writing good code is an investment, at first, you might feel you’re losing time but it will save you hours, days even weeks in the future. It will be easier for you to understand that code you wrote months ago so you or someone else could build on top of it, debugging(tracking and fixing bugs/errors) will be way less painful it’s like a “find a needle in a haystack” vs “looking for a needle in well-arranged drawers”. So you go faster by writing better code.

So how can you write better, cleaner code? Here’s a non-exhaustive list of things to do.

1- Folder structure

The way you organize your package, folders, files, and code matter a lot. You don’t expect to find your socks in the fridge, right? Ok, maybe. But when you organize your files and folders you make it easier for you to modify the codebase because you know exactly where your “socks” are.
The way you organize your folders and files might differ depending on the programming languages, frameworks, or the size of the project. You can structure your package by feature for large projects, by layer for very small projects. But favor package by feature as most projects tends to grow.

//Package by layer ├── adapters │ ├── HomeAdapter │ ├── SignInAdapter ├── viewmodels │ ├── HomeViewModel │ └── SignInViewmodel ├── views │ ├── HomeView │ └── SignInView ├── models │ ├── Home │ └── SignIn

Simple, easy to navigate if the project is small.

Even if this is organized by feature, there a layer separation: ui and model. In a big project, it would be easier to navigate through the various files.

2- Naming

You’ve probably read this somewhere: “There are only two hard things in Computer Science: cache invalidation and naming things.” Phil Karlton.

Naming things correctly is hard, but very important. Make your function, class, file name as explicit as it’s not necessary to read the whole class or function. A red flag is when you thinking about a different name when looking for a file or a function, that means that you need to refactor the name.

When you’re naming your class use a noun — class represents a blueprint of a real-world object. It’s better to use a single word to name your class, avoid using acronyms and abbreviations, and use a capital letter for the first letter, ie Car, Employee.

When you’re naming your function or method, which describes an action use an action verb + what, ie displayName, increaseTemperature, etc. It’s not a good idea to use more than 4 words in a function, keep it short and to the point.

When naming functions that return a boolean, use closed question + what, ie isFull, hasMoney, isOverheating. Careful using negative closed questions like isNotFull, since it can be confusing sometimes.

For your variables favor short words but precise, employeeName is better than just name. Think of them as labeling a bunch of drawers for a stranger who likes to ask what is inside of this and that. What do this variable holds, and what’s the context, Name of an Employee becomes employeeName.

Avoid using obscure naming or one-letter name, aaa, p, xxx 👀. Sometimes we can use a one-letter name for temporary variables that are scoped in short functions, like r for radius inside a function that calculates the circumference of a circle, or i for iterator inside of a loop.

Be consistent in your naming, sometimes some functions do the same thing but in different contexts or inside different classes, like showUser and displayUser, keep the consistency across your project.

Using these tips will force you not to create class/functions that do many things at once, your function should do one thing and do it well, that will help you to name it more easily.

3- Readability and Conciseness

Programming languages are praised for being concise, like Kotlin, Swift, Python but dreaded for being verbose like Java so does your code. Concise means clear, short, and comprehensive. Conciseness is the balance between short and clear where clear is more important.

Don’t sacrifice readability for conciseness. Why? Well, most of the time we don’t really read code, we skimmed through them, if it lack readability it will take longer to figure out what the code does and that will slow you or someone else down.

I think of conciseness and readability as the UX of code, make your code as intuitive and simple as possible.

“Everything should be made as simple as possible, but no simpler.” Albert Einstein

4- Comment

Commenting is very important, but comments are like using salt in cooking, use it sparingly, and don’t use it for just every recipe. We’re not talking about documentation comment but code comment.

Don’t state the obvious, let your code do that.

// Calculate the radius of a circle <- This is bad fun calculateRadius(circonference: Long) { ... }

Comment can encourage us to write bad code, the thinking goes like: “This code is unreadable, I’ll add a comment.” Comments are not there to explain what the code does, remember your code should be readable, comprehensible, with proper naming. When we use too many comments, comments that explain the what, we tend to write poor code.

Comment should be used to explain what your code can’t do which is explaining the why and should be as short as possible.

// Always use the BarFactory for creating Bar objects because it //guarantees they will be initialised //using the correct Config. <- This is good fun getBar() { ... }

The what → the naming, the how → the code, the why → the comment.
The why is not always necessary.

“Don’t comment bad code — rewrite it.” — Brian Kernighan

Conclusion

Structure your code well, so it’s easier to navigate through your files. Name your classes, functions, variables properly, add comment when necessary to explain the why, strive for readability more than you do for conciseness. If you do those well, your code will be cleaner and more maintainable.

Looking forward to the part II.

Find me here: jephtecolin.com

From Civil Engineering to Software Developer, how I followed my passion

Jephte Colin — Wed, 07 Oct 2020 14:10:02 +0000

When I was a kid, I wanted to be an astronaut 🚀. Growing up, I realize it might not be a fun career as I imagined from watching those cartoons. I always found science and technology fascinating. As a young kid, I used to tear my electronic toys apart just to have the chance to see the inside which always fascinated me, that’s how far my curiosity went. I would scavenge motors, LEDs from broken appliances so I can build stuff with them, I once build a boat using foam and a motor. I couldn’t dig deeper into electronics, due to lack of guidance, it was the late 90’ there weren’t many computers in Haiti, let alone the internet.
Fast forward a few years, I’m a teen who can’t even open a browser and surf the web. I had to get help from a friend and from that work my way up, I would often visit cyber cafes to surf, playing games on websites like Miniclip, Dragongamez. I was fascinated by how huge and cool the internet was.

I found my passion

By the time I reach my late teen I was quite proficient using a computer, started to learn programming on my own. I didn’t own a computer back then, I’d use a friend’s computer, my sister’s, or the school computer every time I get the chance. My first programming language was C, I learn the syntax, do some minor exercises but never did some big project. I was learning it wrong, I didn’t know anybody that was a programmer that I could ask for help. I read a lot as an avid reader, while it was a good thing and that helps me have a birds-eye view of programming, but I wasn’t good at all at building things, because I wasn’t practicing. Then I started learning Python, I was amazed at how simple and concise the language was, I was more into hacking than building software. Hacking was just hard. A friend then approaches me and advised me to learn how to build software instead of learning how to break into computer systems, it did take me time to realize he was right. So I started to learn HTML and CSS. Still, I enjoyed reading but didn’t practice enough, yet I have a good memory but nothing can come close to practicing when it comes to programming. I learned that the hard way, took me months or a year 😔 .

I chose the wrong career
In my last high school year, I had no clue what should I do next. Yes, I love programming and it was obvious for everyone. But I was thinking that I should not go to university to learn it cause I can do it on my own. I thought of going into Finance or Civil Engineering. Well, I went into Civil Engineering in 2013, I liked it but not enough, I would skip classes, never work the Math, Physics, and Statistics so I can spend time learning on my computer or watch TV shows.
In the end, I got suspended for a semester because of my low GPA. It was always a battle for me, I wasn’t happy, and all the classmate could see that. I was dragging myself to class but my mind was elsewhere. I was supposed to graduate in 5 years but I realize it would take me 2 more years. I didn’t see myself pursuing a career in Civil Engineering. After about 4 years of Civil Engineering courses, I take one of the biggest decisions in my life…
I DROPPED OUT and I said to myself in a year I’m going to be a software developer. My family didn’t take that lightly though, but they eventually got over it. With the money I was saving for about a year, I bought a computer and made myself the promise I’d learn and build a career in programming.

I followed my passion

I then continue learning Python, Java. But I spent most of my time playing video games on my computer, I didn’t build much. I was going through books and online courses just so I finish them but I didn’t learn anything. When it comes to software development, you have learned something when you can reproduce it. Otherwise, you would think you know it until it’s time to do it. I was trying to read and memorize syntax, piece of code instead of letting them sink in by practicing regularly. Well, that didn’t help much. One day, while using a defective console controller on it, after a few seconds the computer suddenly shut down and it was the end of it. I so regretted that, but what I regretted more was my failing to keep my promise to the point I fall into depression. It was a real battle. I saved money to buy a second computer and managed to get it by January 2018. I said to myself I won’t make the same mistake again!
I decided to build Android apps. I wanted to build a real estate app, Kunuk, where users can browse through properties they can buy or rent. So I started learning Java, the modest experience I had in C help me a lot, but Java was a different beast, so I learn while building the app. I work at night because we would have electricity from 11 PM to 4 AM, and I was more focused at night. It was exhausting but I was passionate, happy, and sometimes mad when I can’t fix a bug or can’t figure out something. I’d use Stackoverflow a lot. I used a board as my Scrum board and a few stick-it papers, so I can stay organized. I asked a few friends to test the app and I would release a new version every weekend. I was finally learning the right way, by practicing, by building, but reading was also in the mix and watching video tutorials.

By March 2018, a friend of my girlfriend told her about an Android Bootcamp, organized by Codepath Haiti led by Carly BAJA, who also has a Software Development Company, Transition Digitale. I signed up immediately, then they requested me to build a simple Todo app by following a video tutorial to be eligible. I built it, and after a few weeks, I’ve been approved. I would have to move to my cousin’s to Pétion-Ville, a city 200km from home, and spent two months to attend the Bootcamp. I had to take a break from Kunuk so I can be focused totally on the Bootcamp which was quite challenging. But I did my best. My final group project was a public finance app for the government which a government official, a designer, and I built. That app would later serve as a Minimum Viable Product to help Transition Digitale land a contract with the government to build the full system, where any citizen can have access to various ministry budget and spending. I joined Transition Digitale(we work remotely) and the Codepath Haiti team. I could finally be independent and take care of myself, I moved definitely to Fermathe, 30 min from Pétion-Ville.
I had the opportunity to teach with the Codepath team, we went to Les Cayes, my hometown, to Mirebalais and Delmas. I had the opportunity to be coach by other developers, but due to a lack of managers I ended up being coached to be a Product Manager, cool but I wanted to code. So in my free time, I pick up Kotlin. A few months later I have the opportunity to teach JavaScript at a professional school, I didn’t know very much about JavaScript. Well, I was teaching while learning JavaScript which helped me a lot. I then learn ReactJS, NodeJS.

Final thought

Software development is hard! There’s no doubt about that and anyone telling you the opposite might be well, not a real developer. The sooner you bear that in your mind the better because you’d be prepared mentally for the hardship. Learn by building stuff. Connect with other developers. I’m doing that because it’s my passion, and it makes me happy. I enjoy doing it, I enjoy the process, the lifestyle, the power where you get to build whatever thing you imagine, the money! I make sure that I improve day by day because things change fast in this industry.