First Time Working With Others?

Question

I've been at my very first programming job for about 8 months now and I've learned incredible amounts so far.

Unfortunately, I'm the sole developer for a small startup company for internal applications.

For the first time ever though, I'll be handing off some of my projects to someone else when I leave this job. I've documented all my projects thoroughly (at least I think so), but I still feel nervous about someone else reading my code.

For example, I've always done this sort of thing.

for (int i = 0; i < blah.length; i++)
{
//Do stuff
}

Should I name 'i' something descriptive? It's only a temporary variable, and will only exist within that loop, and it seems that it's pretty obvious what the loop does with 'i'.

This is just one example. Another one is that I name variables differently... I don't really conform to a standard of naming besides starting all private members with an underscore.

Are there any resources that could show me how to make it easier for the next developer? Are there standards for this type of thing?

Answer 1

Code Complete by Steve McConnell is a good place to start looking for the answers to your questions and a whole lot more you haven't asked yet but will soon.

Answer 2

Here's a good article that should help you:

http://msdn.microsoft.com/en-us/library/xzf533w0(v=VS.71).aspx

You could also spent a little time and get to know your "Refactor" command before the new guy sees all of your bool aintSo = false; language all over creation.

Answer 3

There are 2 tools that I know of that can help you a lot. StyleCop and FxCop. Follow the links to get an idea of what these tools are all about. The big advantage of having these tools is that you will not have to go through your code manually, which would undoubtedly take a very long time.

Answer 4

Besides the point of "actual work" (--the previous 3 answers are pretty good--) keep in mind that we (programmers) are an arrogant (and pretty much ignorant) bunch of weirdos;

No matter how hard you try to write good (and well documented) code or how much syntactic sugar you'd apply: to the new guy your code will always "suck" (at least to a certain degree) since he didn't write it.

For your example (using i for loop), it's only a local loop variable. I wouldn't be too hard on yourself. As long as the code is pretty much self-explained he'll just have to manage.

Answer 5

This particular construct is common and the 'i' is fine here.

As for the other example, that is subjective and as long as you are consistent in your conventions you should be fine.

Mainly: BE CONSISTENT

EDIT: As for a reference, here is one that you can use:

Code Name Convention Reference

Answer 6

No their aren't any general standards.

Projects (or companies) usually set coding style guidelines for themselves. However being consistent is probably a rule followed by any style guideline.

Answer 7

For variables you're using for iteration, it's common to use 'i' or 'x' for the names. That won't bug most people -- if it does bug someone, then they probably haven't seen enough real code to qualify to do your job. :)

If you're really worried about what someone thinks of your code, then trying to name stuff consistently may not be a bad idea. On the other hand, don't go and risk breaking everything just cause of some obsession with making other people like your variable names, cause someone's gonna hate them no matter what you do. If it works, and it's documented well, and your variable names mean something (aside from the 'i' and 'x' variables mentioned above), then it's "good enough" IMO.

Answer 8

If you've got the following done, it'll go a long way to easing your replacement's pain:

1. Produce an architecture document showing the overall structure of your software and which parts interact.
2. Document every member variable / function / class to indicate what they do (not how they do it).
3. Write and document some tests which show how your program operates and what you expect to happen in ways you expect it to be used. Make sure any example data is recorded so that your replacement can re-run the tests to gain an understanding of how it should work.
4. Make sure your code follows a standard. Even if it's not a conventional one, code that is at least consisten with itself will be easier to follow.
5. If you're comfortable with it, leave some contact details so that the guy or gal who takes over can at least email or give you a call if they're really stuck. I've done this for various projects / jobs. It doesn't take long to answer the odd question but it can easily save the pour sould who's inherited yuor codebase a lot of time.

If you want a coding standard to adhere to, there's a relevent post here on SO which has some suggestions.

Answer 9

One of the best ways to learn to write good code is to read good code, so you could try downloading some open source projects that interest you and browsing through the codebase to see what other people do. There are a million answers to "what is good style", and clear consensus is not always easy to do.

The absolute best thing you can do to make things easier on the incoming programmers is to make sure you have good face-to-face communication skills. This can be easy or difficult depending on your own particular comfort and outgoingness and also on the other person in question. There are some things you can do to make it easier on both of you, be sure not to fall into the trap of communicating solely by email or code comments is a big one. If you have a report with the newcomer then they will come to you when they have questions instead of puzzling over code you created in a hurry and muttering to themselves.

That said, the best code is self-documenting. Use comments where necessary, particularly for method descriptions or tricky bits of business logic, but try to ensure the code itself is readable enough in most places. This enables you to avoid reducing code readability with too many comments.

A specific answer to your question, there are no need to rename simple counter variables such as i. In fact, i and x are commonly used in that situation in most c languages so anyone with familiarity with those languages will be very comfortable. Other variables, particularly class member variables and those used within methods, really require decent (though not too long) names.

Answer 10

Usually, the least useful is a variable (eg. counter), the shorter the name is. 'i' is quite a standard so don't worry about it. The important variables, though, as well as variables having a long life time should have a descriptive name.

As it has been said, be consistent (have all you vars to begin with a lowercase for example, choose to use or not to use underscores...).

Keep your function bodies less than 1 and a half page (except maybe for the main function), with descriptive and consistent name too.

And finally, comment the hacks, not the obvious :)

Answer 11

I can tell you from experience: others don't write beautiful code. Really, if your code is somehow documented, it's already quite better then the average.

Don't be nervous. There are hundreds ways to write the same. Every developers thinks his way is the best. IMHO, the only thing that matters about coding style is consistency. So if you've "always done this sort of thing", you have consistent code.

Answer 12

There is absolutely no substitute for working in a team, especially during the early years of your career.

The amount you can learn from other more experiences programmers is invaluable. There are several models of learning that suggest to reach the highest levels of ability (to be an expert) you have to be able to converse with other experts. Having peer relationships with those a few levels above you will help you learn far faster than reading books and websites will.

A lot of the other answers here are good, and give good resources for learning a lot of great stuff, but I'd make sure you're next job is with real people you can learn from.

Answer 13

Amongst variables i is considered a special naming case. Along with j, k and l, i is well-understood to be a temporary "counter" variable for use in loops. As long as your use is consistent, this wont be a problem.

Here are a few good rules to follow for making your code easier to understand:

• Be consistent: Make sure your variable naming conventions and design is consistent. If you often create temporary variables for loops, are they always called i? Do you use i anywhere else to mean something different? Consistency means there are patterns of logic to your code. Patterns are easy to pick up and follow.
• Explain yourself: Make sure that comments explain why you are doing something, not what you are doing. Comments like // Loop over array don't help; anybody can read your code and see you're performing a loop. What they want to know is why you're doing it.
• Document your classes: Giving somebody documentation about the purpose of every class, interface, member, property, even if it's just a single line explanation, is a huge help when trying to understand what the components of an application do. If you turn on XML comments in Visual Studio, it will generate a warning every time you forget to add the bare minimum of a summary of each member. These comments also have the added bonus of intellisense support, making your code even easier to work with.

If you can say your code follows these guidelines, I would be pleased to inherit your code. Frankly, I've yet to be given a codebase that followed even one of these bits of advice, but I write my own code in an attempt to make thenextguy's job that much easier.

Answer 14

Everyone thinks that everyone else's code sucks. And you should think that your code sucks too. Why? Because it does. It really does.

http://stackoverflow.com/questions/679621/how-to-overcome-the-everyone-elses-code-sucks-attitude

I know that when I have to maintain someone elses project and wade through their code, I find myself mumbling four letter words about the person and the job and the people in charge... Eventually though, I do reach a point of understanding and can grasp how the person thought about the problem and their coding style.

It's not easy to adjust to other folks coding styles, that's why teams have coding standards and code reviews. These things help ease the pain... at least in most cases.

If you have documented your code and your project (i.e. what does this thing do?) and your programs are in production (actually being used!) then the next person shouldn't have much to complain about... except your code :)

Answer 15

I find ii to be far superior to i as my basic loop counter. I don't remember for sure, but I believe I learned that technique from Code Complete. Why is it superior? Try searching for i in your source. Then try searching for ii. See which works out better.

Answer 16

Conventions, comments and documentation are great, especially if you manage to explain what the programs are for and why you did things one way and not another.

If practical, I also suggest spending some face-to-face time explaining the projects to the new developers before you leave. That's invaluable.

Answer 17

I will be blunt here, but please have in mind that there is also a balance to be found.

Do what you are paid to do. Especially true for contractors. Do you force your style on others. Follow the company's coding standard and formatting standards.

Now if you are confident that the standard the company is using, is somehow wrong. You bring it up and explain first. Once a consensus is in place, you can use the new standard straight away and get a bonus (tap on shoulder) that you help keep the standards.

When in doubt, ask someone! Help you integrate with the existing team. When you become more senior, then others will come to you.

And a final word, the code belongs to the company that paid it and not the developer, so don't hold it like your baby.

Answer 18

This should be obvious, but make sure every single production component has the source code readily available, and in a compilable state. Make sure there are no machine specific settings required to compile your apps, since the new person will likely get a new machine.

If you are leaving soon, I would strongly recommend against refactoring your code to adhere to any "standards". Good style is important, but not over introducing new bugs that might need to be fixed by the new person.

And your apps are in source control... Right?

Answer 19

If you must name "i" something different, call it "index". In a loop with as much (lack of) description as you've posted, that's the only appropriate name to use.

Sometimes when looping over a "blah" array, it's appropriate to call it a "blahIndex". This is especially true when there is more than one index being used against more than one data structure. A format like "blahIndex" will remind the mind which index goes with which item.

That said, it's a generally understood convention in the programming world that a variable called "i" is an index. That means that keeping "i" as-is shouldn't confuse anyone.

Answer 20

OK, I'm going to be a contrarian here.

The reason everyone gets away with writing poorly commented code is that at the end of the day, few people ever go in and muck with it.

The real legacy for you to leave your company is programs that work well and do what the business folks need done.

How the code is written is much less important than whether it accomplishes something useful. The easiest program to maintain is the one that never needs to be changed because it does what people want it to do - no fuss, no muss, no bother.

Answer 21

I've experienced a times where the original code guy put a project off by weeks because he didn't want to "expose" his code to another coder. That is all i remember about his code. And about him as a person.

Answer 22

I've seen someone use Index, Indexx, Indexxx and so forth as counters. He now works for McDonalds.

To cut things short: I'd rather see i, j, k.