Martin Fowler, Refactoring: Improving the Design of Existing Code:
Any fool can write code that a computer can understand. Good programmers write code that humans can understand.
And so, the reason why programmers typically spend only 30% of the time writing new code and features; the other 70% is wasted trying to figure out what the old code, written by somebody, or even oneself, is accomplishing. All reaffirmed with a recent VB 6.0 program that I must port over to .NET and C# - I have been spending the past week in low productivity as I slowly in a murk of confusion attempt to make sense of the instructions the computer is asked to performed. (It doesn't help either that I continue to dig out new information and code blocks that meet requirements I have not been briefed about.)
Contary to popular belief, programming is in my eye more an art form than an application of science. Ok, it depends on who
your intended audience is - the computer that will simply run your produce, or other developers who will
inherit your source code to modify it. Remember that software, like all other man-made things of this planet, rarely remains at v1.0. And it is safe to say most programmers write code for the former. The latter is of no concern.
And perhaps here is where the major difference is between a mere programmer and a software engineer
. One who perceives him/herself as a professional engineer, will undoubtedly factor in quality engineering into his/her work. In this context it will be code blocks written with such refine and polish and working smoothly like a beautifully designed engine with ultra precision standards.
Code that reads out so naturally like a poem. A resultant product so immersive in its elegance and grace that makes one go, "wow!"
Is it truly that difficult to write code easy to read and understand? Or has everybody subscribed to job security
? Here are some pointers I will highlight from the project:
Short cryptic variable names For some arcane reason, traditional programming academics had always taught us to shorten our variable names as much as possible. So brilliant is one to go ahead with
Dim i As Integer
Dim j As Integer
Dim p As Integer
Dim x As Integer
Dim y As Integer
Dim z As Integer
Even when they are quite obviously loop counters, spanning them across a thousand lines of code to track various matters becomes a haystack needle search. I am guilty of it sometimes myself, but at least I limit such short-named variables to small scope blocks.
Modern programming languages allow long variable names, so take full advantage of that. Give everything a meaningful name. Multi-word if necessary, spelt out in full English. Don't try to squish the letters into some unpronounciable tongue-twisting game.
Similarly named variables working together And then, don't name variables working together with such close proximity that programmers can actually start wagering amongst themselves if they guessed their purposes right. As with above, distinguish them clearly with full phrases.
Up til now, i still struggle to remember the difference between nArryTag and arryTag (two arrays) as they are placed side by side for comparisons of their values.
Humongous multi-dimensional arrays Nothing beats trying to remember what myArry(nNumRec, 13) is versus thatArry(nNumRec, 8), especially when different columns contain different data types. When trying to represent a complex object with a mulititude of fields/properties in a non-Object Oriented language, please try to think of Data Structures.
String positional manipulation A variant of the above, thousands of lines of inter-mixing Asc() Val() Mid() CInt() operations on a single string, coupled with using them as condition checks is a great way to lose bracket () count. To be fair, the string being so often manipulated is in actuality byte input streamed from serial port devices, so chopping for protocol is necessary. But at least it would be helpful to refactor them out to methods/functions to explain what is being manipulated/checked.
Different data types to represent the same thing One array represents status by characters, another in the same function uses integers. Dates sometimes written as strings. In program as well as database. Please, decide on the data type and apply it across the entire project implementation.
Nested (lots) conditionals that span hundreds to thousands of lines A matter of preference apparently. However I reckon that code should do only as much as it should and get/break out. It is not fun flipping pages trying to find that ending curly bracket or End If for the very first condition. Instead of the "conventional" approach
Line #451 If <something positive> Then
' do positive
' with more If Else
Line #894 Else
' do negative
' with more If Else
Line #1428 End If
try to finish up jobs as quickly as possible
If <somethin negative> Then
' do negative
' Anything beyond is other business
With the latter approach I seldom have to ident my code several levels to produce that "neat" looking left margin (read: wasted space, unless you like drawing lines with rulers to connect the "end points")
Of course I know time constraints usually do not grant the luxury of thinking up of short genius expressions
; it is often said perfection is achieved not when you have nothing to add, but when you have nothing left to remove. And that is difficult. Writing short and effective code is. But I am learning.
Because I am writing code for the future developers who will take over my code, not the computer. I want them to sing in joy instead of curse in anguish. I want to make mine poems. How about you?