Readability of Code
- Subject: Theoretical Tutorials
- Learning Time: 0
Consistency: this applies to formatting, using braces, naming (variables, classes, methods) and directory layout (if you bury a source directory somewhere under /css I’m coming after you with a machete); Having said that programmers have a bad habit of thinking they will remember where it is or they cannot forget about this file EVER but after 20 minutes away from the computer suddenly the work falls apart because YOU CAN’T FIND THE FILE. It is your duty build this organisational skills which will server you years to come where you logically store the files, name the variables, functions and follow the same style of organisation on different project. Always follow consistency.
Size: if a function doesn’t fit in its entirety on the screen in a normal IDE at a normal font size then you need a pretty darn good reason as to why not. Of course there are some valid cases for much longer functions but they are greatly outweighed by the egregious examples. Decompose as necessary to keep your functions simple; if a function does not need a part in it then don’t include it there. Either comment it out or delete the unnecessary lines. Your code gets thrown into the compiler which then compiles every line before producing the results, if you want to think from a compression stand point then it’s better to have a smaller source code file so it’s easier for the compiler to produce the final product. It’s always a good thing when it comes to memory management because the program will be less bloated on the memory if the size of the source code is considered.
Comment judiciously: there is a tendency for some programmers to use comments as a substitute for readable code or to simply comment for the sake of commenting (like /* finished */ comments right before return true. Seriously, what’s the point? Most (good) code explains itself; This is a good and bad thing, If you are a student and learning to do this then commenting on everything you do will be probably be the most important thing in the project, your tutors will insist you do it. By doing so you are giving an insight into the code you have written and explained what it does.
If you are working with other people then it’s different HOW – code comments sever a very important purpose it helps us communicate with others through the code and mention what is happening and may be show our logic through it, however as its said before GOOD CODE EXPLAINS ITSELF but it won’t hurt to comment something about it so its easier for someone to find what they are looking for without reading the whole thing first. Commenting also increasing the search function of the code, example if you comment where the key functions are then if I don’t know what the function is called then I can simply search for it using some keyword like “converting binary” or “pickup weapon” and if its commented properly that will help to jump to that section quickly.
Never Cut and Paste within a Project: it’s perfectly acceptable to take a code snippet from one project to another (every project is an island) but you should never take a non-trivial code segment from within one project to some other point within the project. Inevitably one changes and you leave some poor developer with the task of looking at these two or more code segments trying to work out how (and arguably more importantly, why) they are different;
To save time we can often be prone to developing bad programming practices, it helps when we can copy and paste chunk of code from another project to help save time. This can be seen as a bad programming for bigger projects, example you are making a small game then we can use any chunk of code from another project it will still work, however if you are working in a team for a bigger project then it might become a problem because there are certain dependencies that might require other instructions than the one you chosen, in some cases the project will work but it creates a bad habit that can cause lots of problem later on.
Avoid Repetitive Code: if you find yourself writing the same sequence of statements (or very similar) over and over again, abstract or parameterize it. If you see very similar statements the tendency is to skim over them assuming they’re all the same (when typically they won’t be in a way that matters).
If you find yourself writing the same code over and over again, time to stop, re-evaluate and reduce the code. Example – in many of our own tutorials we have used picture boxes to show a player, platform and many other things. Most of them need to have an event linked to them now if we have 7 picture boxes and we create an event for each then we will have 7 functions that essentially do the same thing. We can create a simple event that links to all 7 picture boxes this will reduce the code, reduce the memory load and in effect make the game better.
Use whitespace to separate disparate areas of code: For example, indent code blocks like “if” statements. Leave blank lines between methods/functions or related lines of code within a method/function. This allows the brain to segregate the code even before the characters are read. Indentations are very important, since programmer’s code in simple text editors they start to look very generic and there is no way to often differentiate the codes and functions. By creating various indentation methods in the code we are creating something that looks logical and makes it easier to read.
Use meaningful variable and method/function/class names: Follow the standard practice for the language and use terms from the problem domain if possible. The meaning and use of something should be evident from its name. Names should also be consistent (GetX(), GetY() and GetZ() rather than get_X(), LoadYFromDatabase() and getVar(Fields.Z));
Always follow this method, this method will help you keep a career and keep your sanity too. Name the functions and variables in a logical order that makes sense to humans and help you to figure the problem out when its not working.
Comment effectively: Avoid obvious comments (“The GetX() method returns the current value of x”). Comments should say what the code intends to do, how it relates to other parts of the code and any assumptions (“Argument “a” cannot be null. The code throws an exception if a is null”).
Following established design patterns for the language, library or problem space: For example, avoid repeating code (called DRY or Don’t Repeat Yourself). This wastes time as the reader tries to look for differences or find the correct piece of code to fix.
Keep it Simple (KISS principle): For example, avoid premature or unnecessary optimization. Optimization has its place but code can often be optimized without impacting readability.