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.