Embedded Systems October 2000 Vol13_11

Issue link:

Contents of this Issue


Page 41 of 181

= ! = ~ I If following a particular convention starts to impact your performance or development cost, it's time to ditch the convention. Yo u will have to answe r th ese questions fo r yourse lf. But le t's con- side r o ur humble goal. Ijust wanted to create an abstract scalar type th at would te ll the compiler to prevent me from makin g stupid mista ke like "le ngth = time" 0 1 - "seconds = milliseconds." I also wa nted to be able to overload o perato rs so th at th e a nswe rs wo uld come out in the r ight uni ts automati call y. Any pro- grammer who wanted to use thi s class would have to be fa miliar with the impleme ntatio n in o rde r to use diffe re nt units. So much for low mainte na nce. So we have gone to extremes to do what should be a very simple thing, and we still don 't have a good solu- tion. This is probably why, when it come to u ing the right units , most of us rely on code review and testing to ensure that we get it right. Getting it right If you are going to rely on humans to do the j ob of checking uni ts, you might as well make it easy on them. There are lots of ways to screw things up, so the best you can do is to try to make that less likely. The first line of defense in this area is the names YOll choose for your variables. No mode rn programming la n- guages I know of e nfo rce any rules about how you name your data, o r allow you to enforce your own . Many coding conve ntions o ut the re say how you sho uld name your variabl es, bu t they are usually focused o n aes- th e ti cs. It seems we are more con- ce rned abo ut which lette r sho uld be capi talized , or wh e re to put th e unde rscore th an we a re a bo ut whe th er th e name is inconsistent or misleading. Ofte n we don 't realize how ambiguous some terms a re until we have to revisit the code much late r. What seems clear today may be incomprehe nsible six mo nths from now. Consider a term like "rate" used to describe a change in some value over time. You might name a variable "transfer_rate" or "fl ow_rate," but you are missing a key piece of informa- tion-the units. To measure a data transfer rate, you could be talking about bi ts per second, baud, bytes per second, megabytes per second, and so on. Typically you might put a com- men t in the declaration to indicate the uni ts, but if that declaration is in another fil e, chances are good that no one will look for it. Why not use the name to indicate the convention in use? Fo r example, we could use th e name "tra nsfe r_ rate_bits_pe r _sec." T h is te ll s us exactly how it was calculated and how to use it. What if you a re usin g system clock ticks as your unit of tim e measurement? It wo uld be a was te of CPU cycles to scale your clock ticks into seconds. In thi s case, you could skip the scalin g and use a name like "tra nsfe r_ rate_bytes_ per_tick," making it clear tha t you are not usin g seconds for measure- ment. This is not pa rt of a ny stan- dard conven tion , but it communi- cates an important piece of informa- tion tha t th e reade r needs to know. Another programmer should a t least get a clue from th e name that he needs to kn ow what a clock tick is before he makes a ny assumptions about thi s valu e. Putting units in your vari abl e names may seem clunky a t first, but it adds value to your code. For 'one thing, it gives more meaning to a va ri- able tha n a generic term like "rate" or "length ." If the name consists of real- wo rld measurements, the reader can in fe r informatio n abo ut the variable just by knowing about th e applica- tion. For instance, if a variable con- 40 OCTOBER 2000 Embedded Systems Programming Naming guidelines Following a convention like SI goes a lo ng way toward making your code easy to follow, but if following a partic- ular convention starts to impact your per formance or development cost, it's time to ditch the convention. That's where the names are most important. Yo u should be free to use whatever units are necessary to get the j ob done, but use the names to inform the reader. The goal is to make the code as easy to follow as possible, so that code reviews will catch as many errors as possible. Stick to familiar terms and abbreviations in your names using SI as an example (see Table 1) . Keep in mind that the SI abbreviations are case sensitive. For instance, "M" is th e abbreviation fo r "Mega," but "111" is tlle tains the speed of a car in miles pe r hour, you have a fairly good idea what the range of values is fo r that vari- able. You also know that an expres- sion like "speed_mph di s ta n ce_me te rsl d e I ta_ti m e_sec- onds" is wrong. You can see that just by looking at the names. No need to sift through h eader fil es or design documents, it's right there for every- o ne to see. What I like abo ut this approach is that it is simple to apply and follow. You do not need strict rules to apply this, just common sense. You don't need a dictionary to follow the code as long as you stick to familiar abbrevia- tions. A code review can help alert you to ambiguo us abbreviations or unfa- miliar terms. Another benefit of this approach is that incomplete compliance is better than none at all. Even with tens of thousands of lines of legacy code, you can still improve the code by applying this to just the code you add or modi- fy. Unlike some naming conventions that don' t work un less they are strictly followed tllroughout the code, putting units in variable names can be do ne anywhere at any time.

Articles in this issue

Archives of this issue

view archives of EETimes - Embedded Systems October 2000 Vol13_11