{"id":12,"date":"2007-03-21T05:16:08","date_gmt":"2007-03-21T10:16:08","guid":{"rendered":"http:\/\/mariusbancila.ro\/blog\/?p=12"},"modified":"2007-03-21T09:44:52","modified_gmt":"2007-03-21T14:44:52","slug":"the-importance-of-good-code-conventions","status":"publish","type":"post","link":"https:\/\/mariusbancila.ro\/blog\/2007\/03\/21\/the-importance-of-good-code-conventions\/","title":{"rendered":"Make Your Code Readable!"},"content":{"rendered":"

One of the most important qualities of code is, or at least should be, readability. The simple fact that it works\u00a0is not enough. If it’s not readable, it definitelly ain’t maintainable. Thus, our mission, as programmers, is\u00a0to right code, that above being correct, is also readable and understandable. When a new programmer joins a team it takes time to familiarize with the\u00a0application domain, language or code or all. To reduce that time, companies use\u00a0code convension, that in theory should\u00a0make the code readable, but\u00a0unfortunatelly in reality, in many cases, does the oposite.\u00a0<\/p>\n

A long time ago, in a galaxy far, far away there were no rich IDEs and no Intellisense. Programmers had to knew by memory all the types, functions, and variable names. Moreover they had to new the type of variables, parameters or returned values. Thus, naming conventions helped in taming the beast. Probably one of the most famous (and infamous at the same time) convention, at least\u00a0for C and C++,\u00a0is the so called Hungarian notation, invented almost 3 decades ago by Charles Simonyi, a chief architect at Microsoft. It was named so because it made code looked like written in a foreign language, and Simonyi was of Hungarian origins. Nowadays there are a lot of variations of the Hungarian notations, but in the beginning was one called Apps Hungarian, named after the group Simonyi was working in, called Applications, that was in charged with developing Word and Excel. Later, the group that developed the Windows barrowed the convention without understanding it, and developed a second version called System Hungarian. That was evangelized by Charles Petzold in his bestseller “Programming Windows”, probably the bible of windows programmers.<\/p>\n

Though Simonyi had some good intentions and ideas, they were misinterpreted, and that led to a bad convention style. All because he used the term “type” when he actually meant “kind”. In a paper, written in an academic style, he wrote:<\/p>\n

“The basic idea is to name all quantities by their type.”<\/em><\/p>\n

Though he used to quote the word type<\/em>, and tries to explain that a type is defined by a set of operators that apply to a quantity, people did not correctly undestand what he was saying. He used rgX<\/em> to indicate an array of X or “range X”, cX<\/em>, to count the instances of X, or dX<\/em> for the difference between two instances of type X.\u00a0Apps Hungarian was used for Excel and Word, where\u00a0rowWidth<\/em> could be an integer variable specifying the width of a row, and dX<\/em> also an integer variable but specifying the number of selected colums. In his Apps Notation it didn’t make any sense for instance to add dX<\/em> to rowWidth<\/em>, though these were both integers, which\u00a0has an operator + defined. They have the same type<\/em>, but they are not of same kind<\/em>. The original paper of Charles Simonyi was published in 1999 in MSDN: http:\/\/msdn2.microsoft.com\/en-us\/library\/aa260976(VS.60).aspx<\/a>.\u00a0<\/p>\n

The Apps Hungarian focused on the semantic of quantities (variables, functions). In Systems Hungarian, however, the focus was moved on type. With p<\/em> indicating pointer, ch<\/em> characters, dw<\/em> double words, ar<\/em> arrays, sz<\/em>, null-terminated strings,\u00a0or lp<\/em> far pointers, you could see variables named like lpszName<\/em> (long pointer to null-terminted string specifing a name), dwI<\/em> (double word index), arx<\/em> (array of X), but also things like lpararszID<\/em> (long pointer to an array of arrays of null terminated strings). Now imagine hundred of thousand on lines of code written line that. It simply makes my head ache. Such\u00a0notations cannot<\/em> make the code more readable. Only the oposite.<\/p>\n

If you look up on the web, you’ll see a lot of notation conventions for the same language. Even for the Hungarian notations, there are plenty of variants. Here are just two that\u00a0I picked-up randomly with a google search:
\nhttp:\/\/web.umr.edu\/~cpp\/common\/hungarian.html<\/a>
\nhttp:\/\/www.gregleg.com\/oldHome\/hungarian.html<\/a><\/p>\n

I say enough with bad style programming! The days of such notations are long gone. Today Intellisense help you writing the code. When you use an object and type . or -> it automatically shows you the list of functions, variables, properties, etc.\u00a0it has.\u00a0When you write a function name it shows you the prototype, with all the overloads, parameters type and name, and even comments. And many other features\u00a0that replace the need to\u00a0prefix your variables with a long string of letters that you can barely read. Joel Spolsky wrote a very good article called Making Wrong Code Look Wrong<\/a>, where among others he explains why the Hungarian notation fell into disgrace and was replaced at Microsoft with a new one with the release of the .NET framework.<\/p>\n

I’m not going to delve into proposing good convention styles, there are plenty available. I just want to make some points: often, what you think it’s good for you, it proves the oposite in reality. Using bad naming convension is like deeling with a lot of birocrary: too many paper work, no real benefit. Thus I will restrain myself to just a few points:<\/p>\n