Redesign the platform so that hardware-specific API is not visible by default

[vgheo]

At the moment, the hardware-specific API is visible in the arduino sketches by default.
( ie implementation details are bleeding into the Arduino abstract API).

Therefore users can write code like

PORTB &= ~(1 << PB3); // reset bit 3 of PORT B

and even

digitalWrite(PB1 , HIGH); //This doesnt work

This confusion can be eliminated if the hw-specific headers are not included in the sketch by default.
If advanced users really need these defines, they can include the headers explicitly.

Samples:
https://www.instructables.com/id/ATTiny-Port-Manipulation/
PORTB |= (1 << PB3); //replaces digitalWrite(PB3, HIGH);
damellis/attiny#127

[per1234]

I also have seen this misconception about being able to use port/bit notation with Arduino API functions come up regularly, most often with people who are using bare chips rather than Arduino boards. However, your proposal would be a breaking change so it wouldn't be possible to do to the established boards platforms. It could be considered during the creation of boards platforms for new architectures where there are no established sketches using that API to break.

I did some work on the Arduino Language Reference content to try to emphasize that Arduino API functions only take Arduino pin numbers: arduino/reference-en#516

If anyone is interested in studying this issue to identify possible opportunities to mitigate it, I added a collection of references to incidences of this issue in arduino/reference-en#516.