Friday, October 12, 2007

"Public" API's

I have for along time prided myself on writing code that other developers would want to use. It was my brother that actual gave me that definition of good code and i think it is a good way to think of how to write code.

I have recently been using "legacy" code and am constantly amazed that none of the public methods /classes are commented or documented or have argument checks. What I find slightly amusing is the screeds of code that is commented out in certain code files. I have no problem commenting out code while running test etc, but delete before you check it in, that's what source control is there for! Certainly do not release code with all that crap in there...

If you write c# in the .Net framework you probably use VS. Turn on FX cop.
For gods sake its there to make you a better coder, not to just randomly show arbitrary message at the bottom of your screen. If i am working on a project i prefer the set warning to errors from the start, then the code stays clean.

Use ReSharper. Your code will be cleaner. I am the only one using it at my current place of employment and the HUGE amount of redundant code that shows up is unbelievable! It may go a way to explaining why after 14 week the U.I. was still not up and running.

Use GhostDoc. Its makes commenting a completely trivial task and also helps you name methods in a more appropriate manner. If I notice the comments don't make sense then instead of rewriting the comment I now rewrite the name of the method till the comment makes sense. The more you use it the less this occurs.

Check your arguments on all public methods. This is call Design By Contract. I basically check everything that isn't a Boolean.

These things all reduce the chance of you being one of those developers... the one that i curse at as i work with their code.

Look at your code.
Is it clean to look at, with out even reading it?
Can you, at any stage, generate meaningful documentation from your code?
Do you know off the top of your head what the code coverage is likely to be on your current coding project (assuming this is greenfields)? Is it appropriate?

Some colleague I have worked with think this is Gold Plating.
Bullshit. We get paid good money to do our job.
Number one priority is to develop working code on time, sure.
But I believe, certainly as a contractor who may never be seen again, it is also my duty to make it as easy and intuitive for the next guy, of whatever ability, to use, re factor, debug and modify my code.
These practices do not deter from our number One priority. In fact I have found the above implementations, along with TDD, usually mean that you are more likely to handle code once and not have rummage through it again later looking for bugs. And if you do, I guarantee it will be a lot faster than if you had not put these practices in place.

* certainly since I have been a contractor!

No comments: