Being a Programmer

This is an article I wrote for CodeProject in 2008, and has been changed only to the extent
that it fits the context of my own web site. There is no source code and there are no
pretty pictures to accompany this text. Finally, keep in mind as you read this that I've
never been a department head or a project manager, but I have been a lead programmer,
team member, and sole programmer on numerous projects.

Finally, for every programmer, you'll get a different outlook on everything I'm about
to discuss below. I'm not claiming to be a know-it-all, or have some special super
secret knowledge passed down only to me by the gods in Mount Redmond. I simply have a
lot of experience, and I've seen my fair share of flotsam drifting down the sewer tunnel.
If you'd like to share your experiences, please do so on CodeProject. The more
preparation we can give the new guys, the better off all of us will be.

My Philosophy On Writing Code

I have this bizarre outlook with regards to writing code - I do it because it's fun.
I don't really care how much money I make, or that one day I'll become a manager of
some kind - I do it for the pure enjoyment of doing it. It just happens that there are
people out there that will pay me to do what I consider to be a hobby. Sure, I've had
other hobbies, but at some point I reach a level of proficiency that makes the hobby
almost boring. I've found programming to be a whole different animal.

With programming, you become proficient at a language, but the paradigms under which
you write code are fluid, and they can change from one day to the next. Sure, I have a
history of spouting off about how all this new-fangled technology is ruining the
industry, but in the end, that's what keeps me interested in being a programmer. I've
been a programmer (I mean actually employed as one) for almost 30 years. However, it is
becoming more difficult to stay interested, focused, and to put it bluntly, motivated.

I don't do theoretical programming, and I don't write articles about exploring the
latest feature-de-juer that is spewed out of Redmond. Most of my coding time is spent
writing real-world applications that do real-world things, and there is little time or
desire to putz around with the edgy new stuff. I wait until there is sufficient
information disseminated, and thorough examples presented before I take on something
new. When you're developing against a tight schedule, you rarely have time for
exploration.

Being Part of a Team

I would guess that 85-90% of the people that use CodeProject are part of a team of
developers working on a single project. When you're part of a team of developers, you
have to develop a few necessary skills...

Working on Your Assigned Task

When you're part of a team, you will most likely be assigned a specific group of
tasks to perform. If the project is carefully planned, the project manager should be
able to abstract the tasks into reasonable sections that require little interaction
with the other team members during initial development. What this means is that you
can pretty much implement the code any way you see fit as long as the resulting code
meets whatever requirements and restrictions are placed upon it.

I see each programmer on a team as a semi-autonomous unit. He is given a task,
and the bulk of his attention should be to code according to the requirements. Many
times, the requirements will specify interaction between code elements, but just as
many times, the actual design of the code element is left to the programmer. The
more experienced a programmer is, the more freedom he will be granted with regards
to internal design. Even so, there may be corporate coding requirements that he has
to consider, such as the use (or non-use) of certain libraries/assemblies, and the
implementation of certain coding techniques, such as exception handling or class
inheritance (like deriving objects used in a generic list from IComparable).

Interacting With Other Developers On The Team

If you have a question about coding policy, ask the team lead. Chances are that
he's a team lead because he's got tenure, and knows the answers to those types of
questions. Many times, the team lead will have to make it up as he goes. Why?
Because believe it or not, many companies don't have any policies or standards in
place. In that case, it's up to the team lead (and or project manager/department
head) to establish and distribute guidelines so that your work isn't interrupted
by questions like this.

Unless specifically told to do so, do NOT work on tasks assigned to other
individuals. If the task design is open-ended or insufficient, and if that task
meshes or otherwise interacts with a task assigned to another programmer, schedule
some time with that developer so that you can see if he has any specific
requirements. After (or during) the discussion, write down what was said. Along
the same lines, evaluate your tasks and ensure that you have a clear understanding
of how the different components work together. Identify questions early on, and
try to get answers before you start coding.

Note: My short-term memory is really starting to suffer, and I've often
considered buying a small recorder to take to meetings and design discussions so
that I don't forget what was said. One of these days, I'll get around to it (if
I remember). :)

Suggestions, Criticism, and The Politics of Programming

Many times, you'll bump up against someone else' code that you think could be
made better. Before you spout off, consider the following.

You may not see or understand all aspects of the code that offends your programmer
sensibilities. Before you comment on someone else's code (especially that of a more
senior developer), consider that it probably works fine the way it is, or that there
is a reason behind the implementation. If the original programmer did it right, there
will be comments that allude to his thought processes. Assuming that the original
developer is still with the company, or that someone else has been assigned to
maintain the code, NEVER CHANGE ANOTHER PROGRAMMER'S CODE WITHOUT DISCUSSING IT FIRST
WITH THE RESPONSIBLE PARTY.

Before you call the kettle black, make sure your own kettle isn't black itself. In
other words, if your code sucks, you have no right to say that anyone else's sucks.

Before making a negative statement about someone else's code, make sure that person
isn't currently above you in the general chain of command. If he takes offense (and I
can almost guarantee that he will), you'll find yourself out on the street looking for
work, or worse, relegated to scut work that nobody else wants to do.

If you highlight a problem, have a solution ready to implement. Without a solution,
your comments will, at best, just be shrugged off, and at worst, you will be labeled
as egotistical and/or confrontational.

Develop the skill to know when to shut the hell up. Many times, it's better to
bring up your concerns, followed immediately by a hasty retreat. If your concerns have
merit, (and especially if you've provided a solution), changes will be forthcoming.

If you spout off, expect to be tasked with fixing the problem. Now do you see why
it's wise to have a solution ready?

Code to the Specification

When given a task with a specific set of requirements - above and beyond ANY other
consideration - you should always code to fulfill precisely those requirements. Many
times, the schedule leaves no time for interpretation or adding flare or panache to the
code. You simply code to the specs and move to the next task. Of course, in a perfect
world, this works just dandy, but in my world, nothing is ever "perfect". The
requirements might (and often are) deficient, or it hasn't been made clear to you how
much leeway you are granted where embellishment is concerned. This is especially
troublesome when the requirements haven't been completely fleshed out.

If you haven't been expressly told that you have such leeway, ask your team lead or
project manager before doing anything outside the requirements. This is especially true
if you're in a shop that hands out small, seemingly unrelated tasks to individuals that
don't necessarily have a grasp of "the big picture". When you're performing maintenance
coding, you will find that the requirements will be very specific. Generally, if you
don't encounter a problem with side effects or something of that sort, it's best to
simply toe the line. At the same time, don't be afraid to ask questions when
appropriate.

As a side note, I'd like to mention that before posing a question to the higher-ups,
RESEARCH THE CODE and be doubly sure of how the code interacts with the program. You
can perform research by asking the guy that's responsible for the code in question
(that's the fast way), or by digging into it first, and then verifying that the code
works the way you think it does. Only after you've fully evaluated the situation
should you bother the guys in charge. After all, they're busy too, and you don't want
to establish a reputation as being lazy, or worse, an idiot.

As a final reminder, go back and read the previous section. Be respectful, and mind
your tongue, especially if you're new to the team, department, or employer.

Writing Code

Now that we've gotten the interpersonal skills out of the way, I can talk about the
fun stuff - actually writing code. This is not going to be a lecture about the evils
of reverse Polish notation, nor about what *MY* coding style is. Instead, it describes
how YOU should code. The short version can be summed up in a simple phrase - it
depends on who you work for.

Employer/Customer Coding Style

During the almost 30 years I've been programming, I've been in precisely two shops
that had anything that even closely resembled coding style guidelines. Both of them
were defense contractors. In fact, they even had user documentation guidelines (for
instance, we had to use the word "shall" instead of "will"). I'll tell you right
now - every place you work will be different. Unless you're the first and only
developer, you're going to have to work with someone else's idea of proper coding
style.

The best way to handle that is this - code in the style that already exists in the
given source file. You probably don't have time to change the positioning of curly
braces or alter the naming convention. Besides, you could possibly completely break
the code in the process of "beautifying" the existing code. When you get right down
to it, maintaining existing code is NOT the place to assert your manhood. Just take
the red pill and ignore the white rabbit.

Coding Style - Develop Your Own, and Stick to It (When You Can)

No doubt, you've been hacking out your own code on your own system, and on your
own time. That's a good thing. I use those occasions to refine my coding style (but
it's so perfect that "refining" it would actually be a step backwards :) ). You will
find that many times, if your current employer has coding style guidelines, they will
closely match yours. In that event, Bob's your uncle, and life is rosy.

You'll find the biggest difference is in the placement of the beginning curly
brace, and minor issues regarding the use of white space, tabs, and alignment. Take
my advice and don't bother arguing your point. It'll just annoy your boss, and waste
both your time and that of your boss. If you waste too much of your boss' time, you'll
find yourself changing the position of curly braces on your resume.

Commenting Your Code

This is most of the original message I posted in the Lounge earlier this week, and
that gave me the impetus to write this article. I added everything above because I
thought what follows was too short to be called an article. Even if you don't pay any
attention to everything that came before, please pay attention to what follows. Years
from now, you'll thank me.

So there I was, sitting there at home and waiting for the DirecTV installer
technician to show up, and thought I'd work on some code for a new article I'm writing
(this is not that article). I had pretty much finished with the code and was running
through it, adding comments and exception handling, and it struck me - this is the most
unexciting part of programming. No wonder it's so hard to get people to do it well,
much less do it at all.

Writing code for a CodeProject article is fun, and can be quite fast when you make
certain assumptions about the objects being used and data being manipulated. Once you
get it working, you think, "Ahhh, it's almost ready to release." Of course, my desire
to release the code is almost always tempered with a desire to make it self-documenting
and somewhat bulletproof. Adding comments and exception handling is tedious drudgery -
something I equate to ditch-digging, yet it needs to be done. You have to be a
philosopher (no matter what you do, it seems like it's never enough) and a clairvoyant
(anyone using this code might try this or that) to perform this task effectively.

I've been working for three hours, and I've only covered two classes. In the end, it's
a pain in the butt, but I bolster my attitude knowing that even if my efforts might not
be appreciated by a single person, I'll be able to maintain the code properly in the
future.

I have advice for anyone just starting out as a programmer, regardless of the language
or platform you're targeting:

ALWAYS comment your code. It's best to do it as you go, or at least once you've
completed the bulk of an object's code. If you don't comment as you go, you probably
won't have time to go back and rectify the situation. Being lazy up front causes
maintenance problems down the road.

Never assume that someone knows what you were thinking. If there is ANY question
about your intentions, document it in comments.

Don't be afraid to be verbose. Partial sentences can sometimes convey an incorrect
perception of what the code is doing, and why it's doing it. Comments do NOT cost anything
as far as the compiled size/speed of your assemblies are concerned.

In the case of Microsoft tools, make appropriate comments within the Intellisense
system. There is NOTHING that ticks me off more than trying to use an object and finding
out through trial and error that a property is read-only.

USE COMPLETE WORDS! Code commenting is not a valid "texting" environment. Using things
like "Ur", or "plz" just pisses off the adults.

Every property delegate, constructor, and method should have an Intellisense comment.

Make it a practice to appropriately comment your own personal code, and you'll find
it easier to do in code you write for your employer/customer.

If there is a possibility that another programmer (or even you) could provide invalid
data as a constructor/method parameter, VALIDATE the parameter, and throw an exception if
that parameter is invalid. Make sure that you add a comment (Intellisense!) stating that
exceptions are thrown in the event of invalid parameters.

In Closing

The items I've listed above is collectively called "discipline", and if every programmer
developed "discipline" to a higher level, legacy code will be more maintainable by the new
guys coming into a company or project.

Commit to excellence. Follow through with pro-active practices. This is how you gain the
trust of your employer/customer and the respect of your peers. In short, be a mentor before
you have a student, because you're expected to lead by example, and the junior programmers
will look to you for guidance.