Thanks for lilstening to Deep Fried and thanks for taking the time to blog your experience after listening to the show. Reading your post makes the long nights of recordings and post production work worth it to know we may have helped someone.

Great read.

Thanks,

Keith Elder
http://twitter.com/keithelder

I agree that comments can have their place, but just using them without thinking and describing everything can be a waste of time. A well named method – for example, “moveFirstItemToEndOfList”, shouldn’t need any more explanation if the context its in is obvious. They shouldn’t be crutch to write unreadable and abstract code. If you are writing easy to understand code, the rest of team should be able to just follow it. That’s the theory at least!

Try writing an enterprise level application with a minimum of 20 people and millions of lines of code without comments. For the first month it will be fine. the 2nd month will be irritating and the 3rd month you will be doing nothing but answering other peoples queries.

Comments should do 2 things.
1: Tell you what the method/class does (and not how it works)
2: mark problematic or unfinished code with TODOs (unfinished code does exist in the real world and it needs some way of maintance).

In order for this to work.
Methods should be small (200 lines is way too big)
Methods that are in effect State machines should be commentted for each state change.
Methods and Classes should be well named.

But mostly
Abstraction is not your friend, unless you need to do the same thing twice, something normally reserved for API’s.

BTW java developers have a documentation from code generator its called javadoc.