Comments on: Why I /do/ document and unit test http://www.kismith.co.uk/wordpress/index.php/2009/01/17/why-unit-test/ Incessant Ramblings Sun, 03 Apr 2011 14:07:44 +0000 hourly 1 http://wordpress.org/?v=3.2.1 By: Kev http://www.kismith.co.uk/wordpress/index.php/2009/01/17/why-unit-test/comment-page-1/#comment-10456 Kev Sat, 17 Jan 2009 20:38:26 +0000 http://www.kismith.co.uk/wordpress/?p=103#comment-10456 Sure - there are plenty of cases where it's worth commenting. In fact, I comment every method, parameter and return type for some projects - my point is that for the greatest number of cases, nothing more is required than the signature to know what a method does - for well factored code. Definitely policy comments, like the Freevo one you describe, are invaluable. Sure – there are plenty of cases where it’s worth commenting. In fact, I comment every method, parameter and return type for some projects – my point is that for the greatest number of cases, nothing more is required than the signature to know what a method does – for well factored code.

Definitely policy comments, like the Freevo one you describe, are invaluable.

]]> By: Dirk Meyer http://www.kismith.co.uk/wordpress/index.php/2009/01/17/why-unit-test/comment-page-1/#comment-10455 Dirk Meyer Sat, 17 Jan 2009 20:00:17 +0000 http://www.kismith.co.uk/wordpress/?p=103#comment-10455 I agree that code should be self-documenting, but if I use a library from someone else, I don't want to read the code. Some nice doc string is everything I want. "Can I provide a NULL pointer her?" Yes, I can look in the code to figure it out, but why not say so in the doc? And about inline doc: two years ago I found a special "if" handling inside a function in Freevo (I guess I wrote myself). And I wondered: how can this happen? Since then I add a small comment "handle special case because if the user did this two minutes ago, this can happen". I agree that code should be self-documenting, but if I use a library from someone else, I don’t want to read the code. Some nice doc string is everything I want. “Can I provide a NULL pointer her?” Yes, I can look in the code to figure it out, but why not say so in the doc? And about inline doc: two years ago I found a special “if” handling inside a function in Freevo (I guess I wrote myself). And I wondered: how can this happen? Since then I add a small comment “handle special case because if the user did this two minutes ago, this can happen”.

]]>