Programming The Sierras

Insights to high quality software development

Page 3 of 3

Global Variables

The ability to maintain and service a software system is inversely proportional to the number of global variables.

This is a rule/maxim/axiom (whatever) I have gained a conceptual understanding of through years of working on a number of different systems.

The more global variables in use the more difficult it will be to debug or modify it. The fewer — the easier it will be to debug or modify. Not to mention that fewer globals will lead to fewer bugs.

I’m amazed how many Programmers don’t understand or practice this.

And Session variables in ASP.NET count too. Though if done properly (wrap it in a property with a get/set pair) this doesn’t have to be a violation.

Conversely, the scope of a variable should be as tight as possible. A variable should be accessible to a block of code is the best, a single method is normal, a module is OK but anything beyond that is a NO-NO.

I feel I shouldn’t have to explain this one. Just don’t.

Attire

I used to silently rail against dressing up or even dressing well. “It shouldn’t matter what I wear – people should respect me for who I am and not what I wear. People who put so much attention on what they wear or how they look, they- they are shallow.”

Right?

Wrong!

Dressing sharp is important and worthwhile.

For the first thirty years of my career as a software developer I wore jeans and t-shirts mostly. For the decade plus years spent working at home often it was robe-and-slippers. But then things changed after I started going into an office and I dressed sharp; black slacks and suspenders, solid colored dress shirt and a tie and sometimes a bow-tie (!). It wasn’t all the sudden like that but the change did happen over only a few months.

Surprise-surprise but people treated me differently, with respect. Clerks in stores, waitresses, cops (!), co-workers, etc. They all sat up a little and took notice.

It became problematic at some work sites as I intimated some people dressing like an exec or someone important so I’ve had to tone it back a bit (just slacks or jeans, suspenders and solid colored dress shirts). But still, just the suspenders set me apart and qualify as ‘dressing sharp’.

It pays to wear signature attire. For one thing I’m known as ‘that guy that wears suspenders’. I’m also the guy that wears all those different Hawaiian shirts but that is a different thing.

Even nice jeans. suspenders, and a dress shirt (no tie), which I consider daily wear will garner a ‘you always dress sharp’ from friends.

There is nothing to be gained by dressing down and looking plain. It might be to your advantage to not be eye catching – if you’re committing a crime. Otherwise it never hurts to stand out.

I’m Not a DBA

I don’t have any DBA certification or have done any kind of specific DBA training but over the past thirty-five years in the school of hard knocks I’ve learned much about database design and administration. Enough that can hold my own in a conversation with a true DBA, that I have even corrected DBAs in their work. In several shops I have been the go-to guy for SQL questions. I have created databases that have stood the test of time.

I’ve got creds.

GUIDs

Today I am writing about a ‘being too clever by half’ or ‘it’s a good idea until it isn’t’ kind of issue and that is a policy of using GUID keys for all tables. GUIDs have rescued us from many problem like “how do you get the record number before you’ve stored the record” and how do you merge records from two databases that both have index numbers the duplicate each other.

In case you don’t know what I’m talking about; GUIDs or Globally Unique IDs are big long numbers random looking numbers. And they are not sequential but they are unique. They are great for record tables.

I assert they should not be used for reference tables.

I think this is common DBA vernacular: record tables and reference tables, but if it isn’t it should be.

In my own words:

  • A record table is one where you store transactions or multiple sets of information like employees or customers or addresses. Another way to look at it is they store objects, things.
  • A reference table is where you store values for something, a value used in a column in another (record) table. It can be as simple as a Color table consisting of a single Name column containing rarely changing data like “RED”, “GREEN”, “BLUE”, etc. I’ve seen it as complex as this Color table consisting of ColorID (a GUID), Name, CreatedBy (a GUID), CreatedDate, UpatedBy (a GUID), CreatedDate and Active columns. Having an index of any kind is overkill when the field is the key.

Table Names:

The name of the table for all users can be user or users. Plural or singular; either one works in most cases and there are lots of discussions about this. But I don’t want to get into a knife fight.

Be consistent whatever you do, please.

Me? I name my tables in the singular form. If we are going to use one form for all tables we have to allow for the possibility of a table that will only ever hold one record (a settings table for instance).

The Value of Learning to Program

Everyone, everybody should learn to program computers:

  • Programming, computer science, software engineering, hacking or whatever you want to call it is the pinnacle of Problem Solving and Troubleshooting. Two skills you can use in all aspects of your life.
  • It is a humbling mental discipline to accept that something you wrote, something you created is incorrect or inadequate (wrong) and that you ‘need to get over it’ and just fix it.
  • It exercises the brain to think of all the gotchas and not make excuses for not handling all of them. This expands your thinking for more ‘out of the box’ approaches.
  • There is still opportunity to make good money. Maybe not like there once was but it is much better than digging ditches.
  • If you understand programming you can understand using computers better.

Once upon a time it occurred to me everything a computer does it does because a programmer was presented with a problem and found a way to solve it. This even comes down to the level of the fact that the cursor blinks at the speed it does is because a programmer made it blink at that speed or allowed you to set the speed at which it blinks. This screen looks to you the way it does because a programmer figured out a way to render the information based on his available tools or built tools to do it.

And, unlike when I was first learning in the mid ’70s, today the resources are plentiful. You can get a real computer for little money, you can get compilers, intrepeters and IDEs for free and there are lessons for the asking. Click through or find your own. There is no excuse.

Start!

NOTE: I’ve recently started a project creating an arcade style browser game. I’m writing it in JavaScript which is a silly language compared to others like C or C# but the real point I want to make is that it is FREE to write in JavaScript: no IDE to buy (I’m using NotePad++ which is Free but may be switching over to Visual Studio which you can still get for free), free tutorials, Chrome is my test environment and web hosting is as basic as you can get. Very powerful and mature libraries like jQuery and Angular are available for free. Also what is cool about JavaScript is the development cycle (edit, (compile, deploy) test) is fast-fast-fast.

Documentation Done Right

Example:

OK, lets say, and this is my favorite example, you just finished your document, an eight page, single-spaced technical document. And in it you highlight all the important stuff in red. You show it to your boss and he asks ‘Why is all that in gray?’ You tell him why but he comes back with ‘… Red? I’m color blind. Change it all to bold Comic Sans.’ So you have to go through all your documents and change red text.

But lets say, instead, you applied a style. Invent a style if you want, call it Important Text. Don’t call it Red Text, that isn’t abstract and style names should confer a use and not a visual. So instead of coloring the important sections red, you apply this style to them. Important Text may be red if you want, but when the boss needs you to change from Red to Bold/Helvetica all you have to do is just change the style definition and – boom – it’s all fixed up.

Most amateur documentation is cluttered, uneven and doesn’t flow smoothly. Documentation done right is clean, lean, easy on the eyes, easy to read and just the formatting alone can help the reader achieve better understanding of your product. Professional grade documentation is actually very easy to do, just takes a little discipline and a little know-how.

It took me a second to understand this but what my boss told me once upon a time is at the root of Documentation Done Right; he was reviewing the user manual I had written and said “Don’t insert any blank lines — adjust the paragraph style to include space before or after it.”

Ah ha! The germ of an idea.

I had been separating paragraphs with blank lines. Easy enough to do but what if you miss a blank line between two paragraphs by accident! Using blank lines cause questions to immediately come up: ‘when do you use one blank line?’, ‘when do you use two?’, ‘when don’t you?’ When do you use Helvetica? When do I use Times Roman? See — it opens the door to all kinds of inconsistencies.

This even hearkens back to the very first resume I ever wrote. My then boss looked it over and without missing a beat pointed out “That header is indented too far. It is about 1/16th of an inch further in than the rest.” And he was right. As you will see below this would not have been a problem if I had applied the golden rule of documentation.

The golden rule for professional documentation is ‘Only Apply Styles!’.

Conversely, professional documentation has no blank line!

Don’t insert blank lines, don’t italicize text, don’t change font, don’t bold, don’t do any of that; instead, apply a style. And heavens forbid: don’t use spaces (gasp) or tabs to indent text, no, instead you should use an indented paragraph style (say, “SubSection”).

Word and other full power word processors come with this capability and they come with an array of predefined styles. Get to know them; use them, add to them, change their definitions.

If you find you have too many styles then you will have a messy document, restrict the styles to ones that really have real uses.

Ironically I don’t know how to edit the styles in WordPress.

Even web pages in HTML should follow this rule, only instead of ‘styles’ it uses CSS  ‘classes’. Just define the style for a particular tag type and/or class and never set the font or attributes in the markup itself. HTML 5 makes this even more-so with semantic tags like <header> and <footer> etc.

Word has an Outline mode which is my go-to method of writing most everything. Styles are applied automatically to section headers based on their level of indentation which is perfect. I just add the styles of Notes and CodeSample and my work is done, at least the formatting work.

If you stick to this rule your formatting will be consistent throughout, you will use fewer styles, fewer fonts (free tip: too many fonts is bad), etc. so the documentation will be clean and uniform and very professional looking.

Comments

I used to hate commenting my code. Most programmers hate commenting their code. But, properly commenting code makes for good code if it is done properly. And it really isn’t that hard to do.

Good comments:
  1. Explain something that isn’t obvious.
  2. Or explain why something is being done in a non-standard way.
  3. Are complete and full sentences.
Bad Comments:
  1. State the obvious.
  2. Don’t state anything.
  3. Or are just plane wrong.

Bad comments just get in the way of reading the code for what it is. Often a comment is correct when written but the code changes making the comment wrong and misleading.

I will allow for writing out the logic in pseudocode comments first, then coding it proper. That’s OK.

I’ve worked on legacy code commented with fragment sentences stating the obvious. Arrrrrrrg. I delete those. I don’t need a comment to notify me /* local variables */ or /* loop through */. I can just read the code to see that.

Comments are for Programmers, from Programmers. So don’t explain standard programming techniques.

If I have to spend time to figure out something I leave a comment to the effect, in order to save the next sucker that comes along the effort of figuring it out again, especially if that sucker is me. This has become more of an issue lately and it’s value is clear to me now. Don’t figure out things more than once.

I want:

  • A comment when there is a magic number in use, though it would be better to use a properly named constant.
  • Examples of expected input, especially for parsing functions/methods.
  • Comments when something that is just a little different than the usual so that I don’t think it is a bug or just badly written.
  • Comment when we are making use of a function’s side effect (yikes).
  • Whenever I took time to figure out a section of code I comment my conclusions so nobody else has to re-discover it.

Update:

I was prepping for Hurricane Marie (I think) by putting up plywood over our windows with the assistance of my nephew, Andre’. I was labeling the sheets: which window, which direction, etc when he observed “Notes to future self.” Genius. That sums up what comments should be – notes to future self.

Anything you had to spend any time figuring out should be written down so you don’t have to figure it out again. Duh.

In 2014 I worked on a project for Verizon Data Service (formerly GTE Data Services, or “G-TEDS”). I was reviewing a million lines of code when I came upon a file that started with a big block comment describing what the module’s purpose was and why it was needed and the ins-and-outs of it. Nice. Then I found I had written it back in 1995!

Programming Languages

This is a list of the computer languages I’ve learned over the years mainly so I can put it all in perspective, just for me, not that I’m bragging about it (OK, yes I am, just a little):

  • FORTRAN – 1973. I taught myself from Daniel D McCracken’s book A Guide to FORTRAN Programming. which I later found out is the go-to book on learning FORTRAN programming. Also, what I have since then learned about FORTRAN is that the best optimized compilers are for FORTRAN so supercomputer programs are written in FORTRAN. There are even C to FORTRAN converts to fill this need. On the other hand using compiler directives can generate the same code from C as FORTRAN so I don’t know what to do.
  • Wang 600 Machine Language – 1973. 640 words of 16-bit memory is all we had to work with and my senior year crowning glory project was a 3-D graphing program.
  • COBOL – 1982. OK, I paid my dues…
  • BAT – 1982 (scripting language, sort of). We did cool stuff with BATs.
  • Turbo Pascal – 1984. I loaded this on to my brand new IBM AT and re-wrote my 3-D graphing program.
  • C – (1983) 1985. This is where the rubber hit the road, this is where I really learned how computers worked. My manager, John Kimmick, told me ‘the make-break point of a great C programmer is a conceptual understanding of pointers.” So I did.
  • MDL – 1993. AKA MicroStation Development Language. Made me lots and lots of money churning out tools in MDL and working on Verizon’s legacy system. This was an unfortunate disincentive to learn OOP.
  • Visual Basic – 1995. Wrote Link Fixer Plus in VB6.
  • Java – 2002, OK this is the only language I learned from a formal course. It was a 8 hours a day for five days and though I had done tutorials and small projects on my own before I did learn, especially about object oriented programming.
  • C# – (2002) 2010,
  • PHP – 2004,
  • VB.NET – 2006,
  • SQL – 2006, OK, I learned it in 2006 but mastered it in 2011,
  • ASP.NET – 2010,
  • JavaScript – 2010,
  • jQuery – 2011
  • CSS – 2003 (not that it its a real programming language)
  • HTML – 1996 (not a language either)

Languages and frameworks I should learn but never have are these:

  • Assembly language
  • PowerShell scripting
  • F#
  • AngularJS or Backbone (I should get better at jQuery)
  • bash (I can get around with/in it)

Amazement

I am amazed– I am impressed by how well poorly written software works. The truth is that code doesn’t need to be well written to run ‘just fine’. It can be pretty damn sloppily written and it will run about the same as exquisitely crafted code. At least at first glance.

Sure, it would run a fraction of a second faster if it were smartly crafted. Of course, it would be easier to maintain, it would be easier to find the bugs if it were well written. But the bottom line is sloppy code still runs.

One very big company I worked for had an intranet tool with mis-matched tags in the HTML and poorly formed SQL queries. I discovered a method that did nothing; it just copied a list of objects and then threw the new list away, returning the original list; the method didn’t do anything except waste a few CPU cycles. But the program still worked fine. Mostly.

And for the most part, that is not a problem.

  • It only becomes a problem when performance becomes a consideration — which is always.
  • It becomes a problem when it needs to be debugged — which is always.
  • In becomes an issue when it needs to be modified — which is always.

Recently I’ve thought to cut ‘them’ some slack, give them the benefit of a doubt. I’ve said ‘nobody sets about to write bad code, it is an evolutionary thing where the code is written with one thing in mind then things change so the code had to be changed enough to work with the new conditions but not as slick as if it were written that way originally.’ But then I’ve been corrected by co-workers and, no, there are some bad programmers out there who actually work to obfuscate their code, to make it hard to maintain. to write code that just barely works.

More to the point: there are some programmers out there that barely know how to make their program look like it doing something it should be doing. Sloppy, sloppy, sloppy coding and management (leaving old versions of the solution in multiple folders all over the servers). Some programmers suck.

So don’t rubber-stamp code reviews, don’t assume legacy code is slick or even proper. Clean up code, review your own work. Rewrite whole modules, change the architecture whenever the results would be a better program even if it currently works OK.

 

Writing Software vs. Maintenance

In 2001 I found that software I wrote in 1982, COBOL source code I worked on, was still being sold as a product. The COBOL source code was a product that was still viable. This made me formalize what had been in the back of my mind for some time: the time spent writing a program, a unit of software, is insignificant compared to the amount of time that code will live on and be maintained and modified and read and used. I had spent a summer working on that particular version, three months, yet nearly two decades later it was still very valuable.

This code was very well, very cleanly, written, very efficient and free from bugs. I felt good about this. I had no doubts or reservations about how the code was written or that it might not be as good as it could have been. I knew it was good.

The amount of time spent originally writing code is incomparably small compared to the life of the code. I’m talking about a ratio of a million to one especially if you count the total time a program is used or run.

The idea that a small test module or example snippet doesn’t need to be cleanly written is false. “I’m just going to throw it away,” may be true but it is amazing how often it isn’t, how often it doesn’t go that way. Code has a way of living on. Odds are good a piece of code will be re-purposed or pressed into service even though it was just a trial, a test or a sample.

So take the time to write everything well, cleanly and efficiently.

The takeaway is that you should always-always-always write everything though it will be reviewed as a part of your next salary increase. (I hope that gets through to all you out there).

Hello world!

My name is Brian Roys and I’m a Senior Software Engineer.

When I was fourteen (1973) I saw my first program printout, not the data output but a program listing.  It was from a Wang 600. My buddy, Jed, a year ahead of me was in High School (I was still in middle school), had printed it out “This is a computer program,” he excitedly explained to me, “It does this, then this, then this, then this, all over and over again until this is equal to zero.” I saw that and said “I know how to do that. I can do that. I’m going to be Programmer when I grow up.” That summer I rode the bus down to the University Bookstore (in Seattle) and bought a college textbook on FORTRAN programming (by Daniel D McCracken) and read it cover-to-cover; I knew how to program in FORTRAN.

Since that day I’ve seen the good, the bad and the ugly. I’ve done the good, bad and ugly. I want to share my experience and wisdom.

Newer posts »