Introduction
This is a slightly massaged and extended version of a message I posted in the Lounge a couple of days ago. That message was restricted to commenting code, but it has been turned into a more complete article at the behest of a few individuals who responded to the original message. 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 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, either in the messages below, or in your own article. 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 kettle isn't. 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:
0) 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.
1) Never assume that someone knows what you were thinking. If there is ANY question about your intentions, document it in comments.
2) 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.
3) 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.
4) USE COMPLETE WORDS! Code commenting is not a valid "texting" environment. Using things like "Ur", or "plz" just pisses off the adults.
5) Every property delegate, constructor, and method should have an Intellisense comment.
6) 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.
7) 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.
8) If you're writing code using Visual Studio, learn how to use the built-in debugger. In fact, don't settle for being a "decent" debugger. Strive to be a GREAT debugger, because that's probably where you'll spend 75% of your coding time - tracking down and fixing issues cause by not only yourself, but by others as well. Exercise due caution while debugging someone else's code. Be diligent, and explore all possible side effects that might be caused by fixing an issue. If your shop is truly SDLC-compliant, the testers will regression test a new release candidate, but you should not count on the tests being able to capture every little nuance. (Unit tests are only as thorough as the person writing them.)
9) Don't freak out when someone identifies a possible bug in your code. This may come as a shock to you, but your code ain't perfect, and the more code you write, the more likely it is that you will write code that has issues (okay, "sucks hairy donkey testicles" is another description, but I'm trying to show my sensitive side). The simple answer is that if your c ode complies with the stated requirements, it's probably a simple logic error (this happens to EVERY PROGRAMMER I KNOW), or the requirements might need to be adjusted due to an unforeseen side-effect. Remain calm, and work the problem.
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.
History
10/12/2016: Added items 8 and 9 in the last section.
10/30/2008: Update for minor syntax and content issues.
10/24/2008: Removed the pictures because - well - never mind.
10/24/2008: Original article.
