Go Down

Topic: Arduino Learning pages - minor improvements (Read 515 times) previous topic - next topic

tirbelain

May 01, 2017, 04:53 pm Last Edit: May 01, 2017, 05:32 pm by tirbelain
Hi there,

currently I am scanning through the Learning pages to get to know the Arduino-ecosystem. While I think the entire learning section is quite well organized and easy to understand, I came across two minor things (so far) that I think could/should be improved:


>>-operator

The article describes the sign extension and states that this happens for "esoteric historical reasons". Not only does this sound quite negative (at least in my opinion) but actually ignores one important fact: integral-type variables are primarily used to store numbers which are used for calculations. And because of this, those numbers have to behave consistently. The operation 1 << 2k is a multiplication by 2k. Hence the inverse operation, 1 >> 2k is a division by 2k. This behavior applies to both, positive and negative numbers. Shifting-in zeros instead of ones for negative numbers would break this consistency and make simple calculations way more difficult.

The article also states that "This behavior [...] is often not the behavior you want.". That may be the case for bit-operations, but should not be a reason to present this behavior as a drawback. In my opinion, bit-operations are not a beginner-level topic. Hence, if you use them, you know what you are doing and you are aware that unsigned types are probably more suitable.

Of course, this criticism applies to the source article (Bitmath Tutorial) as well, which otherwise is a really good introduction into binary maths and bit-operations.


static-keyword example

In the example there are these lines:
Code: [Select]

  if (place < randomWalkLowRange){                    // check lower and upper limits
    place = place + (randomWalkLowRange - place);     // reflect number back in positive direction
  }
  else if(place > randomWalkHighRange){
    place = place - (place - randomWalkHighRange);    // reflect number back in negative direction
  }

The code inside the if-statements are a simply clamping place to the bounds (as the place-variable in both cases cancels out) and could be written simply as:
Code: [Select]

  if (place < randomWalkLowRange){
    place = randomWalkLowRange;
  }
  else if(place > randomWalkHighRange){
    place = randomWalkHighRange;
  }



Interpreting the "reflect number back..."-comments, I think the autor actually intended this:
Code: [Select]

  if (place < randomWalkLowRange){                                 // check lower and upper limits
    place = randomWalkLowRange + (randomWalkLowRange - place);     // reflect number back in positive direction
  }
  else if(place > randomWalkHighRange){
    place = randomWalkHighRange - (place - randomWalkHighRange);   // reflect number back in negative direction
  }


This will 'reflect back' the values exceeding the boundaries. E.g. if place == -23, the value exceeds the bounds by 3. Reflecting that difference into the other direction will make place equal to -17.

pert

Thanks for reporting this! I have submitted a pull request fixing the issue in the static documentation's example code:
https://github.com/arduino/reference-en/pull/226

It's a bit beyond my pay grade to do anything with your suggestions for the >> operator but you are welcome to submit a pull request to:
https://github.com/arduino/reference-en

Go Up