I Know that my code is very poorly documented. So I want to focus on organizing and documenting the code. To start with, I started looking for online classes that teach documenting code.
I found very little about commenting code. I did find an interesting article I need to think about a bit more. The general theme of this article is to write code in such a way that comments should be rare. For instance, code should probably be re-written if it needs comments to explain it. Variables should be named in a way that describes what they contain.
I was just about to give up searching. I was thinking I would start by putting header comments before each function or method. This article gives pretty good reasoning not to do that. So this week, I decided to look at just one file — user_main.c. Git does line by line version control. I decided on one small header block at the beginning of the file. This header block will indicate the license, original author, and/or the template source.
I looked to the header comments to know what to pass to and get back from a given function. I have decided to make a new document that describes in better detail how to use each function. This new file will be called UprogrammerFunctions.txt. Since I removed the Comment block from in front of user_rf_cal_sector_set, That is the first function I am documenting in the API.
There is a big block of code in user_init() that all it does is set up the IOs to their initial states. I copied that code into a new function called setup_io_pins() at the end of the user_main.c file. Next, I deleted all the test code I had commented out. Finally, I made a couple of macros in user_config.h called VOLTAGE_BOOST_ENABLE() and another one called VOLTAGE_BOOST_DISABLE()
Note: My definition of a macro is the use of a symbolic reference to represent other code. In this place, I am using VOLTAGE_BOOST_ENABLE() to represent gpio16_output_set(0) to make it a little more clear what is going on. I also created a function in wifi.c to set up the wifi modem called wifi_init() and also put a prototype of wifi.init() in wifi.h. I then moved the two wifi calls out of user_init() into the function wifi_init().
I tried to build and the call to the new function setup_io_pins() caused a linker error. I needed to create a prototype of this function. I put it in user_config.h and it compiled, I uploaded it and it ran just like before I started cleaning up the code. I believe my user_main.c file is much more readable now. I have uploaded the new version to GitHub. Click the firmware link in the right column of this page to go look at it or download it.
I would like to hear about your experiences cleaning up and commenting code. What are your preferences for commenting code.