Like many things in our society, there is also recommended etiquette in coding. There are two practices, in particular, that I find important and useful.
First, it’s beneficial to painstakingly document your code. At the beginning of any program, jog down some lines on what the program is about. Then, before any function, write something about it. If you give aliases to variables or tables that have long names, put down some notes as well. If there is any logic behind the code, make it visible to others too. Often times, folks may understand the mechanics of the code, but don’t understand what the code actually does since they don’t understand the logic.
Below is an excerpt from a document in one of my first coding classes. In our assignments, if we forgot to document our code, we would have 5-10% of our grade taken away.
As highlighted in the screenshot, a detailed documentation is very helpful to not only others looking at your code, but also yourself later on. If a program is complex and there is no documentation, you’ll find it more difficult than it should be to refresh your memory on the code. I have been there and I don’t even write complex code!
Above is an example I had from my programming class. In practice, it doesn’t need to be that detailed, but the description section and the date are necessary in my opinion.
The second practice that I think is useful is to format the code. Normally, we tend to get carried away while coding and neglect how the whole program actually looks. Lines are not aligned. Blocks of code are nested and difficult to read. Brackets are all over the place, making it challenging to debug and understand the code. What I usually do is that after I am sure my program works as expected, I search for a website to help with the formatting of code (it’s easy, just google, for instance, HTML formatter) and have the website re-format the code so that it’s easier to digest.
Minh Quang Duong 