a view of the Marsh ...: Home

Programming is like writing paragraphs, or novels, or novellas. It's communication. If you use abbreviations... and other folks are not in on how those abbreviations came about - aka knowing the context... then it is HIGHLY likely someone reading your programming novella will not understand.

Maybe you succeeded at cranking out lines of code that may have fulfilled what was needed at that moment (e.g. contract, project, or just an addition to some work). However, very little code that sees the light of production - is never read again. WHAT does that mean? It means that someone will have to, at some point, go into your code and discover the context and meaning of what you wrote.

How long is that journey? Will you force them on a dusty & hot walk up/down the rim of the Grand Canyon to the river below? A blustery, snowy trek across a prairie? Or maybe a really nice walk to the back deck to sit & enjoy a view of the Marsh?

YOU are in control of what others think of your code. Communicate to them. Leave more than a crumbly trail of wasted crackers. Enable them to understand the flow, the context, the meaning of all of your code in minutes - vs. hours or days.

DID we (developers, you/me) not learn anything from the many years of work that took place as people slogged through the dusty archives of code leading up to Y2K? Given the code that I've reviewed --- I wonder sometimes that we really have not. OR worse... that those lessons are now lost as a new generation of programmers are growing and not learning from history.

Variable Declarations - 1, 2, 3 characters - UGH

Typing 1 or 2 characters for words that could be 5, 8, 12 letters - does not help! Spell it out! What do I mean... how about...

rs --- what does that mean? The first time I saw that was about 12 or 13 years ago. Not clear at all. No context at the point I read it... turns out it meant "recordset". Well how about that. A big whoop savings of 7 characters - leaving total confusion.
Recently - I saw cw --- much looking around by two of us... this was a variable declaration amongst about another 15-30 declarations (all on the same line) - no commenting of any of these 2 digit variables. No apparent relationship to the other variables, other than they were a similar data type -- which was also "coded". After about 5 minutes... it hit us. Column Width. Really? I was astounded. Why NOT just call it "ColumnWidth" - wow, that would be so clear!

Coding shortcuts - UGH

I realize that many languages enable short cuts - much of that might have been helpful when we were using primitive editors like "Edlin" or even "Notepad" - but really... now... anyone that is professionally writing code doesn't do that still, do you?

Declaring variables of the same data type - all on the same line? Really? Stretched across the code page so far that you have to scroll right? Now to me, it's bad enough that you think that same line declarations is OK... but far enough to scroll on a wide-screen monitor. What are you nuts? The story you're telling me there is that you believe your work is a chore... NOT something that should be admired for it's clarity.

And don't get me started on the coding shortcuts that declare the data type by a single character like $ or %... Sure they are legal. Sure they are faster to type. But really now... in your programming novella - do they really bring the same type of clarity that the actual words would (e.g. String, Integer in this example)... yeah boy... those single character symbols are real clear aren't they? >>> major sarcasm there, in case you can't hear my tone of voice

I write code using Visual Basic.NET. One of the things that I really hate, and hate to see in books or other teachers having their students do is use: single line IF statements. GAWD! that just drives me nuts. I've used IIF and that makes sense in MS Excel cells. But an IF statement that saves a carriage return and an END statement... REALLY? WOW you are going to save so many trees ('er bytes) with that one. Use a complete IF statement and make it clear. If one part of the IF statement won't be used, make it clear that you have analyzed that and note it via a comment. Like this...

If TheDataReader Is Nothing Then
    ' continue, nothing to do
Else
    TheDataReader.Close()
End If

     ***** RATHER THAN *****

If NOT(TheDataReader Is Nothing) Then TheDataReader.Close()

Why make the next programmer have to wrap their head around the "NOT" and scroll their eyeballs to the right. One scan through the complete block gives you full information about what is going on with that code. You won't have to figure out what should take place when the object is empty... the code tells you, because the previous programmer determined there is nothing to do. You won't have to dig into the documentation (if there is any) to know if it should have been handled.

Summary

Code for humans - the compilation (e.g. Build) takes care of making it work for the computer. Your code should be useful to experienced programmers AND more so, to the non-experienced junior developers who will follow in your footsteps.

A couple of Rules...

Clarity to your code, by others, in minutes - not hours or days.
Abbreviations do not save time. Stop using them unless they are fully established in the context of the program and even then... Don't use them.
Your code blocks should not need further analysis "down the road". It should be clear that you completed and applied the analysis already.

Posted: 5/15/2011 11:29:46 PM.
Programming