Commenting practices?

Unit tests and the like are the best forms of code documentation. Some testing frameworks write out a spec of what the class under test should do, giving people a great introduction to how a piece of code works in pure english while also providing very clean way to implement the tests itself.

Examples of that are Scala's ScalaTest or RSpec for Ruby.

I find that unless some weird hacky thing is required by the code in question, it is usually not beneficial to comment it. Also, it adds a lot of overhead because you have to maintain the comments... and maintaining the code and tests is already enough work.

Remember, code with out-of-date comments is worse than no comments at all!

A lot of the time, comments just says what the code does anyway, which is a waste of human effort. And if it doesn't, your code probably sucks and you should refactor it.

Just use testing frameworks.

Some people treat comments as a code smell, a sign that the code could use more descriptive names and a better structure. They will fix the code so it does not need comments.

This works in a lot of cases. However one type of comment that is useful is 'why' something is being done. Sometimes fixes are made for obscure reasons that would not be obvious when reviewing the code later. The comments should not express what the code does (that should be covered by naming) or how it does that (again, the code tells you that), so save your comments for 'why'.

I find that nothing serves as better documentation as to how something works then unit tests.

A hard-core stance is: "if you have to write a comment for your code, your code is broken". Rather than writing explanatory comments, refactor your code so that the comments become less necessary. This applies especially to function names (including their parameters), since they tend to be modified the most, and the comments seldom are updated to match.

Instead of:

// Compute average for the two times
int a = t1 + (t2 - t1) / 2;

write

int averageTime = AverageOfTimes(t1, t2);

int AverageOfTimes(int t1, int t2) {
    return t1 + (t2-t1); 
}

Stale comments are one of the leading causes of WTF's when I'm reading other people's code. Overcommenting has been cited as a "code smell" by several authors, including the authors of "Clean Code".

Personally, I write an explanatory comment for each class (I code in C# and C++ mostly), and occasionally when I am using an algorithm I want to refer to.

I used to be in the exact same situation as you. When I first started I never commented anything because everything was extremely small and I always knew how it worked. But as I continued to expand my code and everything started pointing to each other, I found myself not knowing what certain things did anymore and got lost. I had to rewrite a lot of things so I knew what they did again, and I started commenting everything so I knew exactly how it worked and how to use it in the future. You may think you know how everything works now, but in the future you'll look back at something and say 'HUH?' It's better to comment things now and save yourself the trouble later.

The way I comment things:

Always add this at the top of any function, so you know what it does.

/**
 * What the function is supposed to do, a brief description of it.
 *
 * @param     paramter_name     Object-type     A description of it, do for each parameter.
 *
 * @return    Object-type - A brief description of what is being returned.
 **/

Then throughout your code make sure you comment things that look complicated. When you run checks, put a quick comment like 'make sure this is valid'. For any long lines of code or large blocks of code, add a comment of what that specific section does, to easily find it later on.

Rule #1 Comments should indicate WHY not 'what' (the code already tells you 'what' is happening)

Rule #2 After writing the comment - rewrite your code to read like the comment (then remove the comment)