When people learn to program initially, the most challenging part is usually understanding the logic. The documentation, code structure variable naming parts are the nuanced aspects of programming that are often overlooked. This article aims to share a few of these components that will hopefully make your study journey easier to implement.
Write variable names and descriptive functions
Most professional programmers and beginners at times tend to label their variables and functions with non-descriptive names. This is because the available educational content is to blame. Several books and tutorials that introduce variables and functions don’t label them appropriately. For instance, calling variables “x” and “y” and functions “f”.
Having names for functions and variables is great because the programmer can convey snippets of information on what role that function or variable performs in that program. A function called A variable “x” and “y” doesn’t provide us with any details on what it does and the same goes for the function names “f”.
Another common happening (usually found in educational material) is to have variables with unneeded “things” in the name. For example “my_age” or “the_answer”. In this regard, you can ask yourself what makes the age belong to the programmer or the answer be the answer? These are great questions to ask organizations like https://zignsec.com/.
Sometimes labeling your variables in the context of the program domain and not the problem domain is very tempting. For example, labeling your function parameters “input” and your return value “output”. In reality, this does not provide any useful information that we aren’t aware of already.
Discard comments
While we’re talking about the issue of readability, there’s another method that can be used to improve code, and that technique is removing comments. A majority of code is over commented and you may be wondering why that’s bad. The issue is that comments need to be maintained, just like code.
However, if a code falls apart or displays unexpected behavior it’s seen as wrong. On the other hand, a comment won’t break the program if it’s false or wrong. Causing it to become misleading over time.
For this reason, using comments to explain code can be risky since they can’t be tied to or responsible for the way it behaves.
The good news is, there’s a beautiful tool to explain the behavior of the code. And this tool is known as the programming language you program in. When we write readable code in a programming language, there’s no need for comments that much because the code would describe itself.
So whenever, you feel the need to write comments on the activity your code is performing, try to be mindful of a way you can describe this code instead. Try extracting some code into a different function or naming variables differently.
A general principle is to comment on why the code is the way that it is and not on the activities it is doing.
Record functions and classes
Recording functions and classes would serve as an exception to the above rule. Generally, comments are unnecessary, but they work well to document high-level concepts. There are times you won’t be able to completely fit the job within its name without typing a complete sentence, this makes the name of the function overly verbose.
For a person reading code, having some kind of documentation of the functions and classes can be very helpful, this can be in the form of a docstring or comments. This preserves the reader’s time because they won’t need to read through the entire function or class to determine what it does and what its limitations and outputs are.
For languages that are dynamically typed, this is particularly important. Languages that are statically typed have functions with signatures that specify what its output type is and what its input type should be.
In dynamically typed languages, this doesn’t happen, even if the types of parameters are not given explicitly. If for instance, the function is not documented. The person will then need to read through the beginning to gain an understanding of what shape the parameters need to take.
Good function documentation specifies what the parameters are as well as the output, sometimes this works best with an example, through this, it saves the reader time and the trouble of having to determine the programming language because they can trust the documentation instead. Google’s Python style is a fantastic example of this.