A while ago on Digg there was an article on the Seven Secrets of Successful Programmers. While receiving mix (while largely) negative view points of this being an article to grab notoriety publishing a list. I agree with most comments that this was a simple list that should be covered in most elementary courses and should not be front page material. However I thought it was a good refresher to look back through code and see how well it follows these guidelines… So this post will be my feeble attempt at refuting as well as embellishing upon this list of “secrets” into a more relevant (in my opinion) source of guidelines:
1. Code for human consumption
It is one of the most pervasive misunderstandings in computing that the source code is for the computer’s consumption. Supposedly the reason that languages were developed was to help the programmer speak “English”. In practice, coding for human consumption means coding for clarity first, over efficiency and speed second. My opinion is that while it maybe easier to read a language over 1s and 0s it does not give reason to make the code slow and inefficient. If you can’t read the code then maybe you shouldn’t try. This isn’t to say there is poorly written code guised to be fast - there’s no call for that either. In short if you write good code you should be able to read it in 6 months without a problem because good code is short and sweet (fast and efficient).
2. Comment often and comment well
The comment is the extreme example of a language element for human consumption. Most compilers will strip the comments from the executable program. The purpose of the comment is to tell you (and any future developer) what the program is intended to do. I think that comments are great - but if your code is written properly you shouldn’t need more than a few to describe the workings - however in 6 months when you review the code it’ll help speed the process of trying to figure out why you were insane to write that in the first place. A good indication that you have got the level of comment right: could someone understand what your program does if all but the comments were removed? Comments are not meant to teach someone to program, rather they are there to serve as comments (what an idea!).
3. Layout code to increase legibility
Since the dawn of time books are split into chapters and paragraphs that aid reading likewise the layout of the code can affect efficiency. MVC (Model View Controller) style programming relies on this as bread and butter (but we’ll save this for another post). In particular any code branch (an IF..THEN…ELSE construction) and any code repetition (a WHILE…END WHILE construction) should be easy to see where they start and end.
4. Expect the unexpected and deal with it
Before you open a file, make sure that the file is present. Before you set focus to a control, make sure that the control is visible and enabled. Try to work out what conditions could cause your code to fail and test for them before they cause the program to fall over. Error checking is the most underrated tool that a developer has. And any language that doesn’t give the ability for error checking should be scrapped as soon as possible.
5. Name your variables to aid readability
There are a number of strategies to variable naming. The key is to be consistent and to be as informative as possible. I personally prefer the Hungarian notation style - but whichever style you use, consistency is the key. As in anything in life - consistency is the root (pun) of professionalism - want fast code that easy to read? Be consistent. Even if it sucks (the process or the code) as long as it’s consistent those who forge on behind you will write a kind epitaph rather than curse the day you were born.
6. Keep your functions and subroutines simple
A function or subroutine should ideally only do one thing. One of the greatest sources of misunderstandings, in my experience, is a subroutine that does a number of different operations. This should be split into separate functions for each different thing it is doing so that these in turn are easy to reuse, and the scope of a code change is easy to understand.
7. Scope functions and variables appropriately
Functions and variables that are only used in one module should not be visible outside that module. Variables that are only used in a function or subroutine should not be visible outside that function or subroutine. This prevents any use of a variable or function outside of where it makes sense to use it.
“Programs must be written for people to read, and only incidentally for machines to execute.” - Abelson & Sussman, SICP, preface to the first edition
If I have only one word to part to my padawans - it is consistency - from there simplicity - all else will fall into place.