Question

Once I’ve read in the “Clean Code” book that comments shouldn’t be written because they mess up the code.

On the second hand however, “kohana” code (as one of many) contains extensive documentations and comments before almost every line of code.

I’m creating the project which will be used by user-programmers in the future…how should I write comments then?

To make this more clear – should I:

• Write documentation before each class ?
• Write documentation before each method ?
• Write @param, @return… for each method ?
• Write comments for almost every line of code to make it more clear ?

Answer 1

You should:

• Write documentation before each class
• Write documentation before each method
• Write @param, @return… for each public method

Comments on every line of code aren’t too necessary, but I recommend them on lines of code which would otherwise be unclear or obscure.