How To Best Present Your Code
I’m sure every developer at one point in their career looks back at a GitHub repo in despair, I know for sure I have. Messy commit messages, poorly named variables, and clutter that should have been refactored out long, long ago. In this article, I’m going to cover a number of pointers that will help keep your code looking appealing to employers and your fellow dev’s happy. I will be focusing more so on presentation and workflow apposed to tech specifics, however, I may touch on a few things here and there.
As developers are well aware GitHub will be the most likely place their code will live in the public eye and we all want to make a good impression to our potential employers and fellow dev’s, in many cases it is our CV/resume.
So how do we show our code in a professional manner?
Have an informative README!
One large mistake I had been making prior was underestimating the importance of a good quality README, after all, who doesn't love some good markdown! In your README you should ideally include the following;
- A description of what the code does and how to run it.
- What frameworks, languages, and tools you used.
- A brief explanation of your process and how you came to your solutions (did you use TDD?).
- Screenshots of your code in action.
- Good spelling and grammar.
- A brief overview of what you could do better.
Use your README as an opportunity to show your process and what you learned from pursuing the project, it’s a great time to reflect. Ensure you can explain the code to the best of your ability so it’s clear and explicit.
Spellcheck and indent!
One of my colleagues described code as an art and in many ways it is, we want our art to look elegant and vivid. Two incredibly easy ways to make code clear and consistent is to indent and not only spell check but consider our naming conventions. Ask yourself have you given your constants, methods, and classes names that are suitable for their purpose?
Indentation is a pain to do manually, thankfully living in a community of talented programmers problems like these often get solved fairly quickly and there are many automated tools available. I personally use the prettier code formatter for VS code.
Refactor
Refactoring your code throughout the production of your project will help alleviate redundancy, I find this also helps keep me on track as I’m then not shifting through irrelevant things to find what I’m looking for. Test, write the code to pass the test, refactor! This keeps code DRY (don't repeat yourself). It's far easier to refactor as you go appose to trying to do it at the end of a project so getting in the habit of doing this is really important.
Have good test coverage
Having tests in your code is beneficial for a number of reasons, the first being perhaps the most obvious it shows you have tested your code for potential floors or inconsistencies. In addition to this leading with TDD principles will show your process and help keep your code quality up to scratch. Tests almost provide a narrative to how a program was created, in some cases people may look at your tests to see what kind of behavior you were trying to achieve in your code.
A few additional things you can do
- Have a clear commit history, describe your commits well with good spelling and grammar.
- Include some screenshots of your program in use.
- If you deploy the app include a link (as obvious as this may seem).
Please feel free to take a look at the example I made here, I have tried my best to show the best use of these practices. Thanks for reading as always!
