Make code more readable with comments

Stated briefly, I will only comment my code if I can't write it clear enough. The main reason is that comments are the last thing that get updated and therefore can become inaccurate. This is actually a big issue with me and there are all sorts of methods to make the code more understandable. The downside to doing this is most of the time, only a few extra lines of code and perhaps some very minor performance hits. For example, if I have a function that has 100 lines of code that perform 5 different things, I could just write all 100 lines sequentially. But it isn't easy to tell which lines relate to which of those 5 things. So I would make those 5 things sub-functions of the top function and give them meaningful names. And, yes, I do get as ridiculous as making a sub-function that only contains 1 line if that helps clarify what is going on without commenting the code. The upside of this, besides readable code, is easily identifiable reusable code.

Most people ignore the code commenting but it is probably the most powerful feature to be added to .net. Or C# at least.

We no longer produce separate documents for code. If you comment your code correctly in C# you have no need to produce secondary documentation, Also the documentation give you active intellisense and dynamic help in Visual Studio.

I also use a tool called nDoc which is an open source project from sourceforge which will produce an actual chm Microsoft Help file for your code and it will produce html help files as well. A very valuable tool.

http://sourceforge.net/projects/ndoc/