Sample Question:

sdfsdfsf

JSR Notes:

Style & Convention Are Important

By style we mean things that can be chosen by a particular programmer that are not necessarily standard. And by convention we mean, in spite of those stylistic possibilities, sticking to what is expected and agreed upon by the greater programming community.

"Oh, but do we have to??..." is the oft-heard joyful refrain about commenting and the other conventions mentioned in the Teaching Note. And as a teacher, the response can start with "If you were working for my company..." The main point is that computer scientists and coders are no longer sequestered in their basement or their cubicle working on their own little project. I.T. is now too complex to be handled by individuals, and your code is not just your code any more; it's your team's, your company's, and beyond.

There has to be a "lingua franca" not just in terms of the parts that cannot be changed, like the reserve words of a particular language, but of all other more flexible parts too. In this way, code becomes much more standard, and thus much more easy to understand and to share.

Each company or work group can come to agreement on local specifics, and often times "style guides" will be published or posted. Among the points of style and convention they focus on are the following.

 

Meaningful Identifiers

Either you, many months or years later, or other programmers who cannot immediately get help from you, will surely be re-looking at your code at some point. So you NEED to make your identifiers of variables and methods and classes to be clear. Certainly don't make them too long, but better to err on the side of caution, and be clear, if a little long, in your choice of identifier names.

Along with your identifiers being meaningful, there are also additional conventions for certain programming languages, such as class identifiers in Java beginning with a capital, and Java package identifiers being all lower case; neither is enforced by the compiler, but both are expected by coders worldwide. Other conventions, such as the use or avoidance of the underscore character are more dependent on what is agreed upon at a certain company or organization. camelCasing, though is mainly standard worldwide for Java variable names.

Proper Indentation

Code is so, so, so much easier to read if indentation is correct, and this should be easy to do with most modern IDEs (Integrated Development Environments), simply with a keyboard shortcut or click of a button. But don't forget.

Adequate Comments

You never really understand the importance of adequate comments until you have to go back and try to figure out some code that you once upon a time understood, but you sure don't now... In terms of what to comment, there are two non-negotiables. Firstly, appropriate, clear, and correct pre-conditions and postconditions need to be done. Secondly, any non-standard algorithms should be properly explained.

Commenting is simply something you must develop as a habit of being a good coder. The good news is, like any good habit, once you have it, you don't even think about it; you just do it. Finally, note that along with the ease of practicing any good habit, good commenting takes very little effort when that particular function or algorithm is fresh in your mind.

 

Benefits

Save Money

This comes from the time and effort saved. See next item.

Save Time and Effort in Programming Teams

A programmer sitting and scratching his/her head all afternoon trying to figure out what another programmer made long ago and far away - or indeed yesterday, one floor down! - is wasted time and money, if proper and adequate commenting would have prevented the situation.

A classic, if extreme, example of this was the time and effort needed to protect again the Millennial Bug at the turn of the last century. The issue was the possibility that the year 1999, stored as '99 in certain code, would wrap around incorrectly to '00, rather than 2000. Preventing this in the first place would have been universal adherence to the convention of four digit years in code. And proper commenting on tons of programs (many very old, using structures long since forgotten) would have, and did help. In the end, with lots of effort and lots of money, but thanks to lots of code commenting as well, catastrophe was averted!