Episode 6 - The Inside Scoop on Getting Names in Firmware Right

While long names will never yield self-documenting code, correctly naming things is hugely important. Watch this 8 minute video to learn why using names like read_timer_1 is poor programming practice.
For far lots more about embedded systems (including over 1000 articles), visit www.ganssle.com.

[@w2aew]

Great advice!

[@kristhetrader5029]

Excellent advice and relevant to what we all do at all levels! Keep them coming!!

[@xDR1TeK]

I can't help feeling the prophetic value of this. The only reason I still pick i is because in the loop, it looks compact doesn't intrude into the rest of the code. If I were to use "a", then I would think it is a member variable from someplace. For me, "i" is safe. Nice video, it does sustain my beliefs. I feel gratified.

[@zanekaminski]

About the "i" and "j" loop counter variables... In formal mathematics, we use variables with similar names-i, j, k-in similar places, such as in the sigma summation notation. For simple loops, this removes redundant information that adds little to the reader's understanding. In such cases, helping the reader to obtain a structural understanding of what the loop is doing can be much more important than giving an arguably more descriptive name to the iteration counter variable. If the reader understands the functionality of the loop body, the variable's purpose is typically obvious. An exception to this rule would be when loops are multiply nested. In that case, it is often better to use a more descriptive name so as not to confuse, say "i" from "j." Also relevant are functions accepting a single argument, where the purpose of the argument is clearly explained by the function's name. In those cases, I am likely to use "x" for the variable name. e.g. counter_setvalue(int x) or queue_enqueue(object x). Again, this is just like math. I use underscores to separate things in the hierarchical way Jack described, and sometimes combine two words when they go together in the same level of the hierarchy, as in the above example, counter_setvalue(int x). Hungarian notation is nutty but also often misunderstood. When talking about Hungarian, the "sz" prefix comes to mind, indicating a pointer null-terminated string ("String, Zero-terminated"). For example, char *szName or *szPath. A lot of people think it's useless to indicate the variable's type in the name, since most IDEs will tell you the type. Right. But what about differentiating between a null-terminated string and a pascal-type string, where the first byte (or sometime two bytes) gives the length of the string? These are both usually of type char* but the algorithms which operate on them are totally different. So it's not as useless as it may seem at first.

[@IBITInformatica]

good introspection... I love when you conclude that the first programmers were amateurs... (indeed they were) Your problem was my problem... after passing for a large array on languages I developed the convention that the variable is always 'x'... if a function has only a variable we need just a 'x'... if need more than name them as 'xCount', 'xPerson', 'xPersonNew'...this way you can just with a glance detect code from vars...

[@dylankirdahy9591]

Your videos are fantastic, and this one is really funny! Thanks for making them

[@mwildish]

I still use i, j etc ( FORTRAN was my first language) only when the value is a simple loop counter and has no meaning outside that loop.

[@ollopa1]

After decades of software development and variable naming fads, I've come to the same conclusions. It's nice to see someone else share some disdain for the unnecessary obfuscation in Linux.

[@MarkMcDaniel]

Jack, it's important to note that companies push coders to code at asinine speeds. They don't have time to be as conscientious as you suggest here. They can sparsely comment their code, but have to reasonably abbreviate variable names.

[@FreemanPascal]

Wow, I must be in a different universe. Only 13 comments on this particular subject? As a software developer of 20 years plus, this topic usually elicits as many opinions as there are commenters. It is usually considered a very contentious, "religious" topic.

[@bastonbalexendo9659]

your videos are fantastic

[@1622steve]

I stopped using "i" for index in a short loop after I mistook it for "1" once too often. Presbyopia + (certain fonts) = disaster! [Yes, I learned to code in Fortran 4.]

[@bbrazen]

Are you saying "Miser" notation?

[@david0x00]

www.ganssle.com/articles/misrastandard.htm

[@concr3t3]

timer_usec is an abbreviation! timer_microseconds would be better!

[@Fennecbutt]

Everybody _knows_ that i is used as an index/counter just like you _know_ that these underscores are here for _emphasis_.