Go Down

Topic: Making coding easier with Hungarian notation  (Read 1 time) previous topic - next topic

boylesg

Jan 26, 2018, 11:01 am Last Edit: Jan 26, 2018, 02:19 pm by boylesg
Hungarian notation is quite simple.

It involves pre-pending your descriptive variable name with a lower case character or short string that tells you the type of the variable.

So:

Global variables outside setup() and loop(): 'g_', e.g. int g_nPinNum (this is a personal HN customization that I use)
Class (or struct) data members: 'm_', e.g. int m_nPinNum
    This is particularly handy with set(...) functions in your class
    E.G. void setPinNum(const int nPinNum)
           {
               m_nPinNum = nPinNum;
           }
           If you decide you need to change the descriptive part of the name then it is easy to do in one     
           operation with text search and replace.

Any array: 'array' or 'arry', e.g. int arrayPins[6];
Character array string: 'sz', e.g. char szName[9];
Arduino String object: 'str', e.g. String strName;
Any pointer variable: 'p', e.g. int *pData = NULL;
bool: 'b', e.g. bool bFlag = false;
char: 'c', e.g. char cCh = 0;
int8_t / uint8_t / byte: 'n', e.g. uint8_t nPinNum = 1;
int16_t / uint16_t / int / unsigned: 'n', e.g. uint16_t nData = 1;
int32_t / uint32_t / long / long unsigned: 'n', e.g. uint32_t nLastMillis = 0;

Now you can extend the integers a little if you find it useful, but it will also mean changing your variable names if you change its data type. I don't bother myself and find 'n' for all of them adequate.

uint8_t / byte: 'u8', e.g. uint8_t u8PinNum = 1;
int8_t: 'n8', e.g. int8_t n8PinNum = 1;
uint16_t / unsigned / unsigned int: 'u16', e.g. uint16_t u16Data = 1;
int16_t / int: 'n16', e.g. int16_t n16Data = 1;
uint32_t / long unsigned: 'u32', e.g. uint32_t nLastMillis = 1;
int32_t, long: 'n32', e.g. int32_t nLastMillis = 1;

Now where it is really useful in situations like this:

FirstName + Surname + Age + StudentNumber

Now if you came back to this code 12 months later you might not remember what was going on here.
'FirstName' and 'Surname' are probably string. But what is 'Age'? Is it a string too or is it an object? And what about StudenNumber? Is it a String, a number or some sort of object?

But if you did this instead then it becomes perfectly clear.

strFirstName, + strSurname + szAge + strStudentNumber

It is string concatenation where the first two are Arduino String objects and the last two are regular 'C' or char array strings.

Hungarian notation can also tell you rather a lot about a function as in this example:

String strDetails = formatStudent(strSurname, strFirstName, szAge, szStudentNumber);

Please note that descriptive variable names and Hungarian notation don't have to be mutually exclusive, there is nothing stopping you from using both naming conventions in a complementary way.

Robin2

I object to this being parachuted in here. There was a long discussion about this subject, mostly disagreeing with the concept.

IMHO Tutorials should only be posted here when there is a consensus supporting them.

...R
Two or three hours spent thinking and reading documentation solves most programming problems.

boylesg

#2
Jan 26, 2018, 11:38 am Last Edit: Jan 26, 2018, 11:40 am by boylesg
I object to this being parachuted in here. There was a long discussion about this subject, mostly disagreeing with the concept.

IMHO Tutorials should only be posted here when there is a consensus supporting them.

...R
If you don't agree with it then don't use it.


This is an open forum and it is not, nor should be, subject to censorship because you don't agree with it!

robtillaart

#3
Jan 26, 2018, 11:46 am Last Edit: Jan 26, 2018, 11:46 am by robtillaart
Thanks for explaining,

Hungarian notiation (HN) is indeed one way to help people to understand code on the dataType level.
I personally are not a great fan of it as the compiler will check on that level.

HN does not help to understand code on architectual/design or requirements level which are imho
far more important. The programmer should know WHY to use an uint32_t, or a volatile, static etc.

After 12 months I have more problems wiyh why a certain algorithm was used, how the flow of information etc is, or how does it work at all. Yes it is still important to know what the datatypes of the variables are but these are often direct deducable from code.

e.g. Serial.println(Age);  //   will print the Age, no matter if it was a string or number

Age = Age + 5;   //  clearly a nummeric type

Age = Age + "years"  // bet it will be a String

Yes HN would help in all those case, but it does not explain why e.g. 5 was added


For me it is more important that people give a good descriptive name to the variables, classes and functions.

Would you consider using Hungarian notiation also for functions?

String strDetails = formatStudent(strSurname, strFirstName, szAge, szStudentNumber);
==>
String strDetails = strFormatStudent(strSurname, strFirstName, szAge, szStudentNumber);


How do you handle HN for class class instances?
And fields/methods of those classes?

what is more readable?

if (vkbeKeyBoardEvent.u16ErrorCode == u16ErrorTable[u8ErrorIndex]) ...

or

if (KeyBoardEvent.ErrorCode == ErrorTable[ErrorIndex]) ....


// vkbe - volatile KeyBoardEvent, jus  made that up ...



There are similar style discussions about adding comments to code. Yes it helps people a lot if the comment explains the WHY of the code is written that way. Comment does not help if it just repeats the code, or worse it does not match the code anymore. Choosing good descriptive names for variables makes code readable.

Serial.begin(9600); // open the serial port with 9600 baud

one review later
Serial.begin(115200); // open the serial port with 9600 baud

another review
Serial.begin(config.baudrate); // open the serial port with 9600 baud

while it should just be
Serial.begin(config.baudrate);

Thanks for explaining
Rob Tillaart

Nederlandse sectie - http://arduino.cc/forum/index.php/board,77.0.html -
(Please do not PM for private consultancy)

robtillaart

I object to this being parachuted in here. There was a long discussion about this subject, mostly disagreeing with the concept.

IMHO Tutorials should only be posted here when there is a consensus supporting them.

...R
Think the community is too large for having consensus, I appreciate the link you post to a previous discussion as that is more constructive in the long run.
Rob Tillaart

Nederlandse sectie - http://arduino.cc/forum/index.php/board,77.0.html -
(Please do not PM for private consultancy)

boylesg

#5
Jan 26, 2018, 11:53 am Last Edit: Jan 26, 2018, 12:04 pm by boylesg
Thanks for explaining,

Hungarian notiation (HN) is indeed one way to help people to understand code on the dataType level.
I personally are not a great fan of it as the compiler will check on that level.

HN does not help to understand code on architectual/design or requirements level which are imho
far more important. The programmer should know WHY to use an uint32_t, or a volatile, static etc.

After 12 months I have more problems wiyh why a certain algorithm was used, how the flow of information etc is, or how does it work at all. Yes it is still important to know what the datatypes of the variables are but these are often direct deducable from code.

e.g. Serial.println(Age);  //   will print the Age, no matter if it was a string or number

Age = Age + 5;   //  clearly a nummeric type

Age = Age + "years"  // bet it will be a String

Yes HN would help in all those case, but it does not explain why e.g. 5 was added


For me it is more important that people give a good descriptive name to the variables, classes and functions.

Would you consider using Hungarian notiation also for functions?

String strDetails = formatStudent(strSurname, strFirstName, szAge, szStudentNumber);
==>
String strDetails = strFormatStudent(strSurname, strFirstName, szAge, szStudentNumber);


How do you handle HN for class class instances?
And fields/methods of those classes?

what is more readable?

if (vkbeKeyBoardEvent.u16ErrorCode == u16ErrorTable[u8ErrorIndex]) ...

or

if (KeyBoardEvent.ErrorCode == ErrorTable[ErrorIndex]) ....


// vkbe - volatile KeyBoardEvent, jus  made that up ...



There are similar style discussions about adding comments to code. Yes it helps people a lot if the comment explains the WHY of the code is written that way. Comment does not help if it just repeats the code, or worse it does not match the code anymore. Choosing good descriptive names for variables makes code readable.

Serial.begin(9600); // open the serial port with 9600 baud

one review later
Serial.begin(115200); // open the serial port with 9600 baud

another review
Serial.begin(config.baudrate); // open the serial port with 9600 baud

while it should just be
Serial.begin(config.baudrate);

Thanks for explaining
Look I figure it this way....

You can have strictly descriptive variable names and a comment explaining that all the variables are strings being concatenated.

Or you can just use 'str' in front of your variable names which explains the same thing with a lot less typing.

And no HN tells you nothing about code structure or efficient coding etc.

But it is not designed to do that anyway.

Code structure and efficiency are things you have to learn separately.

Code: [Select]

Age = Age + 5;   //  clearly a nummeric type

Age = Age + "years"  // bet it will be a String


I appreciate this example, but their are situations where it is not so clear cut, e.g. when literals are not involved.

But regardless of literals you don't go mixing your conventions do you?

In your example you would use nAge or strAge regardless - all HN or nothing.

And the u8, n8, u16, n16,..... idea - I personally find it unnecessary and don't use it.

I just put it out there as an option and as an example of customization of HN to suit your personal needs. As the MFC programmers have done with LPCSTR and lpsz etc.

GrooveFlotilla

Wasn't Hungarian notation designed for C?

But we're in C++ here.

(I've asked for a moderator to move this to "General Discussion", because I don't see how it helps beginners, who struggle with datatypes as it is, without confusing them with how the variables should be named)
Per Arduino ad Astra

boylesg

#7
Jan 26, 2018, 12:36 pm Last Edit: Jan 26, 2018, 12:39 pm by boylesg
Wasn't Hungarian notation designed for C?

But we're in C++ here.

(I've asked for a moderator to move this to "General Discussion", because I don't see how it helps beginners, who struggle with datatypes as it is, without confusing them with how the variables should be named)
Who cares? Who says you can't use HN in C++?

Or Javascript, PHP, C#,......

GrooveFlotilla

..because some of those other languages allow you to "add" an integer to a string, for example?


(And because your software ends up looking like it was written by Microsoft in the 1990s, and nobody wants that :D )
Per Arduino ad Astra

boylesg

..because some of those other languages allow you to "add" an integer to a string, for example?


(And because your software ends up looking like it was written by Microsoft in the 1990s, and nobody wants that :D )
Big woop.....that means the HN will indicate that doing so is allowed in that particular language.

GrooveFlotilla

Big woop.....that means the HN will indicate that doing so is allowed in that particular language.
...but makes porting the code (specifically the variable name) to a different language that much more difficult.
Per Arduino ad Astra

boylesg

What is it with the coding nazis in here?

Why is a language independent coding convention causing so much controversy?????

It is a coding convention!

You use it if it helps your coding and not if it doesn't!

And there is ABSOLUTELY NO REASON why it needs to be restricted to any particular language.

boylesg

#12
Jan 26, 2018, 01:23 pm Last Edit: Jan 26, 2018, 01:27 pm by boylesg
...but makes porting the code (specifically the variable name) to a different language that much more difficult.
Utter rubbish!

HN is language independent!

If you want to port your javascript to C++ then 'var strName' or 'var Name' are equally difficult to convert the the C++ equivalent!

GrooveFlotilla

What is it with the coding nazis in here?
Bingo! Godwin's Law.

Check out Torvalds' and Stroustrup's opinions on Hungarian.

I think you'd better arguing for using a better IDE.
Per Arduino ad Astra

boylesg

#14
Jan 26, 2018, 01:39 pm Last Edit: Jan 26, 2018, 02:48 pm by boylesg
Bingo! Godwin's Law.

Check out Torvalds' and Stroustrup's opinions on Hungarian.

I think you'd better arguing for using a better IDE.
Well credit where credit is due as they say.

My line has been, all along, is HN if it helps you.

But the coding nazis seem intent on vetoing HN or any suggestion that newbies should try it on for size.

Quote
I object to this being parachuted in here. There was a long discussion about this subject, mostly disagreeing with the concept.

IMHO Tutorials should only be posted here when there is a consensus supporting them.
It is not entirely IMHO.

Go Up