C - number sorting description - c

Question

I have written a C program which sorts an array of 50 of random numbers from 0 - 255. The highest number once sorted is displayed on 8 LEDs as binary digits. The same for the lowest sorted number. I fully understand the program however I need to write up a brief description of it and am struggling with these two functions:
void binaryLowesttNumber()
{
int remainder = lowArray; /* remainder is what I am going to be left with after taking away the value of the pins,
sets remainder as the lowest sorted number */
int j = 128; // value of pins in binary
int i = 7; // index of current pin
while (i >= 0)
{
if (remainder >= j) //if remainder is larger or equal to the value of the current pin
{
digitalWrite(pinArray[i], HIGH);
remainder = remainder - j; // takes value of pin away from remainder
j = j >> 1; // halves the value of j
i--; // moves to next pin
}
else
{
j = j >> 1; // halves the value of j
i--; // moves to next pin
}
}
}
void binaryHighestNumber()
{
int remainder = highArray; // same as binaryLowestNumber function except the remainder will be the highest sorted number
int i = 128;
int thisPin = 7;
while (remainder > 0)
{
while (remainder >= i)
{
double j = i / 2;
digitalWrite(pinArray[thisPin], HIGH);
remainder = remainder - i;
i = i - j;
thisPin--;
}
while (remainder < i)
{
int j = i / 2;
if (j >= 1)
{
i = i - j;
thisPin--;
}
else
{
i = 0;
}
}
}
}

Answer 1

Concentrate on what the function does (not on how it does that, your code explains that). What does function binaryHighestNumber() do? As I understood you correctly, your function sorts an array of 50 of random numbers from 0 - 255 and displays the highest number on 8 LEDs as binary digit. So a perfectly good and informative comment would be:
/**
* Sort an array of 50 random numbers from 0 - 255 and
* display the highest number on 8 LEDs as binary digit using 'digitalWrite()' function.
*/
void binaryHighestNumber()
...
Try to use doxygen format to document your code, that way it will be easy understandable by others who had worked with doxygen. And document what the function does, not how it does that. See Linux kernel coding commenting or GNU coding standard.
EDIT:
I don't see any sorting done in binaryHighestNumber() function. Are you sure this function sorts the array? As I inspect the function definition, all it does is to display a value stored in variable highArray on LEDs. Maybe a better comment would be this:
/**
* Display the highest number obtained from sorting array of 50 elements
* stored in a global variable 'highArray'
* on 8 LEDs as binary digit using 'digitalWrite()' function.
*/
void binaryHighestNumber()
...
EDIT2:
The intent was, that the question is how the code works and now how to comment it, so here we go. Let's concentrate on binaryHighestNumber().
Basically what the function does, is that it sets gpios high which number corresponds to the bit number in highArray. So for a highArray = 0b10101010 we want to light up gpios numbers 7, 5, 3 and 1 (numbering from 0). For highArray = 0b10100101 we want to light up gpios numbers 7, 5, 2 and 0.
The code binaryHighestNumber() keeps track of a remainder - the number substracted from the number of gpios already examined. The other is i - a value that is equal to 2 to the power of currently checked gpio number. thisPin is used to track the gpio number we currently check and it is equal to log2(i).
At first remainder = highArray and i = 128 and we want to check, if we should set gpio number 7 to high. We need to check if bit number 7 in the remainder is set or not. If the remainder is greater then 128, that means that the bit number 7 is set, that means that gpio number 7 needs to be set to high. If bit number 7 is not set, that means that remainder is lower then 128, we don't light the gpio. If the bit number 7 was set, we remove bit 7 from remainder (ie. substract i, which is eqaul to 128, from the remainder) and then bitshift i to the right by dividing it by 2. If bit number 7 was not set, we only bitshift i to the right.
Now remainder = highArray&0b01111111 and i = 64. We continue the process. If the remainder is greater than 64, that means that bit number 6 is set and we need to set gpio number 6 high, remove bit 6 from the remainder (by substracting i from it) and bitshift i to the left (by diving it by 2). If the number is lower then 64, we only bitshift i and continue.
Then remainder = highArray&0b00111111 and i = 32 and we continue until the remainder is equal to zero. (ie. remainder = highArray&0b00000000.
You can simplify the code, to somewhat easier form, like this:
void binaryHighestNumber()
{
int remainder = highArray; // same as binaryLowestNumber function except the remainder will be the highest sorted number
int i = 128;
int thisPin = 7;
while (remainder > 0) {
if (remainder >= i) {
digitalWrite(pinArray[thisPin--], HIGH);
remainder -= i;
i -= i/2;
}
if (remainder < i) {
if (i != 1) {
i -= i/2;
thisPin--;
} else {
i = 0;
}
}
}
}
or maybe like this:
void binaryHighestNumber()
{
int remainder = highArray; // same as binaryLowestNumber function except the remainder will be the highest sorted number
int i = 128;
int thisPin = 7;
while (remainder > 0) {
if (i != 0 && remainder >= i) {
digitalWrite(pinArray[thisPin--], HIGH);
remainder -= i;
i /= 2;
}
if (remainder < i) {
i /= 2;
thisPin--;
}
}
}
Pay attention to that i -= i/2; is not equal to i /= 2;, when i = 1. Also i have removed while loops, they don't change anything. I have removed j variables, they are not needed and don't change anything.
There is a much simpler way to check each bit in a byte and light up these gpios, but I think i will leave that to you to find out.