Documentation should use more specific types

[matthijskooijman]

Currently, the documention uses types like "unsigned long" (for example here: https://www.arduino.cc/en/Reference/millis). However, this is only correct for the AVR architecture, on e.g. the Due a long is (AFAIK) 64 bit, but the code explicity uses uint32_t. It would make sense to adopt the same explicit approach in the documentation (and, while we're at it, probably apply this to the code of the AVR port as well).

[agdl]

@matthijskooijman +1 I think that actually all the documentation and software should use standard data types like uint8_t, int32_t etc. In this way it is immediately clear the "dimension" of a variable and code can be optimized and standardized

[agdl]

BTW once upon a time someone from the high levels told me that for beginners standard data types are not too friendly...

[matthijskooijman]

BTW once upon a time someone from the high levels told me that for beginners standard data types are not too friendly...

They might be a bit scary-looking, that's true, but the using platform-dependent types of unknown size looks nicer but doesn't work as well. We could consider introducing more friendly alternative names, but then Arduino code becomes even less portable, and things people learn will also be less reusable.

Perhaps a decent alternative is to use the standard names in the docs, but make them a link to a page explaining what these types mean? Anyone that is confused about a typename can click it and get an explanation?

[agdl]

I think we need @tigoe

[tigoe]

I would rather we adopt the Arduino types to new platforms as we go. As you said, Arturo, the point in making them in the first place was to make the language more readable for a non-technical audience. I'd like to maintain that approach as we move to new platforms.

[matthijskooijman]

@tigoe, what "Arduino types" do you mean exactly? There is the custom "byte" type, but AFAIK no other custom integer types are defined. The AVR core and documentation use int and long for the bigger integers, but those can't be portably used on other platforms, since their sizes will be different.

Or is your suggestion to introduce new types (e.g. word and dword in addition to byte or something)?

[tigoe]

I mean the ones listed here, as used in Arduino sketches over the last ten years:
https://www.arduino.cc/en/Reference/HomePage

I'm suggesting that if they don't exist for other platforms, we introduce them, to make those platforms compatible with Arduino as it currently exists.

[matthijskooijman]

@tigoe, Oh good point. Seems I totally missed the short and word types (though "word" is a bit of an ambiguous term in general - I think it originally referred to a machine's word size, for x86 it was used to refer to 16-bit, with double-word being 64-bit, arduino seems to use it for 16-bit on AVR and 32-bit on Due, which doesn't actually make it very useful here). On additional complication with these types is that currently short is signed and word is unsigned, and I don't think C supports just adding "signed" or "unsigned" to a custom type to change its signedness.

So, regarding types, it seems we don't have any Arduino-specific / user-friendly set of types that is complete (e.g. has signed and unsigned integers of 8, 16, 32 and possibly 64 bits wide) and portable. So that leaves us with two options for making this consistent:

• Use the existing, standard types like uint32_t.
• Introduce new types to make the existing types complete.

I'm not so sure what the best option is here. Using standard types makes code, as well as learned concepts, more portable. These types also clearly and unambiguously indicate the signedness and size of the type, at least once you've learned how they work. I'm inclined to stick with the standard types, also because it is probably hard to define a new set of typenames that are clear and unambiguous enough. "byte" is well-defined, "short" is less obvious and "word" is both unobvious as well as ambiguous.

For lack of any well-defined names for specific bit widths, using the number of bits in the type (like the standard types) might be useful. To make the names less cryptic, they could be more verbose, an drop the not-so-useful _t postfix. E.g. types like signed_16bit_int or unsigned_8bit_int could work, though I'm afraid they're so long and verbose nobody will want to type them...

[tigoe]

I'd be more inclined to introduce new typws to make the existing types complete. I have always found the _t extension irritating, and uint8, uint16, uint32, etc, too terse, and too easy to mis-type as unit (not to mention how auto-correct does the same to them).

As for being so long and verbose, nobody wanting to type them: that hasn't been my experience, outside of people who've been classically trained in C programming. Tersness is a weakness, in my opinion. It's one of the things I'm trying to fight against, to get people to use natural language more in code, so it's readable to people from many backgrounds. If we really want programming to be a common literacy, then the grammar of it has to be articulate.

[Breidenbach]

Oooh - back to COBOL! :-)

On Feb 5, 2016, at 8:49 AM, tigoe notifications@github.com wrote:

I'd be more inclined to introduce new typws to make the existing types complete. I have always found the _t extension irritating, and uint8, uint16, uint32, etc, too terse, and too easy to mis-type as unit (not to mention how auto-correct does the same to them).

As for being so long and verbose, nobody wanting to type them: that hasn't been my experience, outside of people who've been classically trained in C programming. Tersness is a weakness, in my opinion. It's one of the things I'm trying to fight against, to get people to use natural language more in code, so it's readable to people from many backgrounds. If we really want programming to be a common literacy, then the grammar of it has to be articulate.

—
Reply to this email directly or view it on GitHub #4525 (comment).

[cousteaulecommandant]

I agree that the [u]intX_t types are a bit cryptic and unnecessarily scary. I have seen implementations that use custom types such as u8 or s32 for unsigned/signed types; maybe that's excessively short though. As for verbosity, what about unsigned8 or signed_32b? (not sure if it looks better with or without the underscore, and with or without the b; I think without either)

As for the documentation, I'd just say "a 32-bit signed integer" when necessary.

re: the original comment, I'm not sure a long is 64 bits in ARM; according to http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0472l/chr1359125009502.html it is 32 bits just like int (the only platform I've heard about that uses 64 bit longs is x86_64/amd64).

[tigoe]

I think @damellis should weigh in on this, as he's more informed than I when it comes to the choices for data type names originally.

[q2dg]

Well...six months ago...#3801

[shiftleftplusone]

about cousteaulecommandant's and tigoe's statements:

the C standard data types listed in < stdint.h > are
int8_t, int16_t, int32_t, int_64_t, uint8_t, uint16_t, uint32_t, uint64_t, (...),
and Arduino should apply to the standards!!
why establish a non-standard-C-compliant datatype just for Arduino?
C is C is C, and either C user who is learning C for Arduino should learn to use the correct rules for standard C from the start - or one day he will fail terrificly in "real world" environments (e.g., gpp on Raspberry Pi) !!