When working we focus more on developing the project, we want to deliver good code, we usually want to have fun while doing that, and we also want to move to new things.
Also, we love to roast old code... Mainly if it is our own code, and mainly if we know that we delivered bad code because we were not having fun, we were working in something that was old and weird and we didn't fully comprehend what was happening, therefore we believe that the code had it comming, it was doomed from its own making, we didn't make it reach that point, we only let things happen. That's one of the lies we tell ourselves to not feel bad about roasting old code, the hard work put by other people. Some even like to distance themselves of it by saying "code has no father", so you should not fell bad if its your work being critised.
But thats not true, code has parents, it was born out of a context. Why is something hardcoded instead of in a config file? Why is a piece of code repeated three times in this file? Why is the test commented out or skipped? Why did you commit directly to the main branch and pushed it to production on a friday night without any revision? Why is the CI/CD pipeline suddenly disabled? Why is there a function marked as deprecated when it is used by half the application and there is no alternative to it implemented? Why you spent two weeks creating something from scratch instead of importing a library?
All of those questions have answers, and usually they can only be answered by the person that wrote that code at that point in time, later they may forget, sometimes it was a big problem and they could not find another way to solve and now, one month later, the answer is obvious but they could not see it back in that time. So, how do we answer those stuff that the code itself cannot answer?
How to make onboarding in a project, easier
Aka.: README.md
You want to start working in a project right away... you don't want to have troubles, to install multiple tools, to have to deal with different environment variables, to have to understand a whole weird way to be able to debug things using step-by-step. Thats why we have README.md files.
A README.md should have everything you need to start working, all the scripts, all the downloads, all the imports, everything. Is it a nodeJS project? Say how to install nodejs using brew in your mac. Better yeat, make a shell script and put it into the README.md so the person reading through it may either run the code or make it manually.
Adding all the necessary stuff to the run the project is important, but just listing it don't solve any problems. Saying that you need FBFlipper does not really explain WHY you need this app, saying you need to set an environment variable to SF_CAPS_LIB_GL_EPKS=1 may solve some bug or error, but which one? and how?
Basically the README.md should have enough information so that a person may start a project, debug, create release and publish things on their own, without having to ask help from other people.
Also, if you can make a .sh file that set's up the whole dev environment, do it. If you prefer to set up the dev environment using a docker image with a basic OS like ubuntu, thats fine too, but do not forget what are the exact incantations to make it work and to get inside it and start developing. If you add some way to interact with your projec you have to explain how to properly use it, otherwise you will have people stopping you all the time to ask basic questions before they even start to work in the project.
Help the code review process
First I'll consider that code is usually reviewed through pull request (PR), and I will use this definition throught this article. When you review code you need context, and you need to judge if the code that was written could be better, if it follows the current best pratices, if there are no pitfalls that the other developer may have fallen into, and if the code really solves the problem that it is trying to solve, but how do you make sure it does solve the problem?
First, you need to make a good PR, one that gives context to the other developers. A good pull request has many things to help the developers that are going to make the review.
- Clear and specific title;
- Checklist of mandatory things to consider the feature "done" with all boxes checked;
- If it exists, the Ticket number and/or link to it in Jira/Monday/Trello/etc, so you can have some extra information on the feature or bug;
- Short description of the problem that you set out to fix in this pull request;
- Information on how you fixed that problem;
- If necessary, context on why you decided to fix it the way you did (why you duplicated code? why you left a todo/fixme? why you left a HACK? why you didnt add tests? And yes, it is acceptable to leave such comments in the code alongside the TODO/FIXME/HACK, dont just leave those there, explain why they are there so the next person may fix them, and no, the git history does not necessarely fills this purpose);
The code review is important, but the context on why you did it is even more relevant. And if you build good PRs, social peer pressure will make that the other developers start to build good PRs too.
Dependencies
So you started a new project, you are doing some math stuff, and it is hard to do it all by hand, so you import lodash, it's a small lib, its self contained, your node-modules only have this one import. Now you want to run some tests, so you import Jest, suddenly you have 145 folders inside your node_modules folder and you have an extra 46MB of javascript code in your project. Usually this isnt really that bad, since the test isnt packaged with your code that you are going to deploy.
Now you are trying to fix a problem, and there is a tutorial online that tells you that the perfect way to sovle your problem isn't by coding the solution, but just importing a new dependency which adds exacly the component you need to fix it. You go and download it, put in the project and done, now you have fixed the problem and you barely had to write 50 lines of code, you are happy, you can go and pick another ticket to fix. But after some time you receive an error message... there is a bug in the new component, you go and look for more information and you notice that there are only 3 articles online about that library and all of them are more or less the same tutorial saying how to use it. You reach for the github of the project and it stopped receiving fixes a couple of years ago, there are dozens of issues open, all of them spaced months apart, there are a few pull requests that are more than a year old, and the repo has as many forks as it has likes, you found a dead library.
Unintented consequences of dead libraries
If you add it to the project as a dependency, now it is YOUR REPOSITORY and YOU HAVE TO SUPPORT IT because the original developers abandoned it and there is no community doing active or semi-active support to it (no one to accept PRs). So take a step back and answer this question: Are you willing to add a whole repository to your project just to close a ticket in under a day? Sometimes the "long way" is the best way... sometimes it is worth to bite the bullet and adopt the new library. But you need to weight it in.
Top comments (0)