I'm currently into documenting my source code and creating infrastructure documents. It's amazing how important these things are, I'd say it's inversely related to how boring they are to doJ .

One of the most important things I've ever learned about writing code was early in my career. I was a young programmer, entering a new job as a part of a VB dev team. The first few months at that company were one of the most excruciating periods of my career. I literally had to "forget" everything that I thought I knew about writing solid maintainable code , and literally go against my better judgment.

 

The first rule of maintainable code I had to learn:

Make your code self describing

I though I knew it all when I entered that new job. I was right out of another project which, looking back, was one of the worst things I'd ever help create.

I really thought I understood the principles of maintainable code:

 

·         Leave good comments in your code

·         Use Hungarian notation in some pre-agreed format(VB 6)

 

That was about it. I had helped create a coding convention document for VB programmers while I was in my previous job and I was pretty zealous in making people adhere to it. That was before I "got" it.

One of the first talks my new team lead gave me included one of the things I would always tell other programmers not to do:

·         Try to leave as little comments as you can in your code

 

Jeez! How was I supposed to deal with that? I kept trying to explain to him that writing comments in your code was one of the first tasks I would ever do, that it makes the code maintainable, that without it, the world would be a big pool of chaos and spaghetti code.

 

He would hear none of that. I had to learn the following lessons:

·         Comments get stale. If the code changes, the comments need to change too. They usually don't. So what you get is bad explanations - meaning bad maintainability.

·         If you have to leave a comment to explain what you wanted to do – your code isn’t self describing. Think about that for a minute.

·         If there really is no other way than to comment, explain why something is done, not what its doing.

·         If your procedure does not fit into a single screen, its too long. You need to divide work into sub procedures.

o        This part was the hard. Sometimes I would show him a procedure, he'd say its too long, and I had to find a way to "artificially" split it into sub-procedures. Once you learn how to do that, you'll never go back. It's addictive – like building LEGO…

o        Event handlers should almost always have only one line – which calls a method to do the work.

·         A method's name should explain what it does : InsertCustomer(), CreateSchemaIfNoExists(), FindUserByID()… and so on

·         A variable's name should indicate what type it is(you can also add scope, but that's about the last straw for readability) using partial Hungarian notation.

o        I don’t care if VS.NET had built in tooltips to show you a variable's type. I won't always have VS.NET available for code reading.

o        This habit comes in real handy when printing code for code reviews

·         Boolean methods always start with "Is":  IsTableEmpty(), IsAnotherLoopRequired(), IsUserInDatabase(), IsPasswordMatching() and so on…

·         Putting headers in your modules is a good idea, because the overall description of the purpose of a module is likely to never change.

 

This is all just the start of a coding habits manual, but I had the most challenging weeks when I tried to simply write code that adheres to all of them. As I've said – not commenting code was one of the hardest to achieve. I've learned, though, that it makes very good sense.

 

So now I'm documenting my own code

And I can tell you, following those simple rules sure as hell saves me loads of time today. I am looking at code I wrote more than a year and a half ago, and I understand it pretty quickly, even though the amount of comments is minimal. However I do find some pretty cryptic things here and there. What can I say, I'm human, and I make mistakes. These are usually the things that you get to right at 3am, with a presentation the next day(ah, the life of a startup programmer…).

My point – yeah, you have to think a little when writing code, but – it totally pays off in the long run (and even immediately), Especially when you're working with a team. I can tell you some pretty horrendous horror stories about bad code, but I'm sure you've all been there. How many of you can tell good stories of code they received was self-documenting and easy to understand? Is that common ? No. I'd be surprised to hear that it is (I'm not talking about Microsoft, ok?)

 

Heh, I'll just link (again) to my favorite "how to write bad code" article:

How to write unmaintainable code

 

Update:

LondonGeek makes a good comment about how comments that spell the *intention* of the code will never get stale.:

 

"Many programmers don't comment, they annotate their code. For example the say "Create an XML DOM and load it with the text file cust.xml" when they should actually say "Retrieve a list of my customers". The second version enables someone to understand the intent rather than the implementation.

This kind of comment will rarely get stale, in-fact it will only get stale when you completely change the intent of the code."

 

 Agreed, however - why would you need to write that comment in the first place? Why not just make it a method named " RetrieveCustomerList()" which is self describing?

 

He also mentions this great book, which I recommend you have on your shelf - which is filled with great discussion about these kinds of problems:

Code Complete

 

Duncan points to this link for programming techniques:

http://www.merrioncomputing.com/Programming/7Secrets.htm