

The Best Code Documentation ‘Tool’ Ever Made - martinnormark
http://martinnormark.com/code-documentation-tool/

======
ASneakyFox
The method comments are where you explain the expected/accepted inputs and
outputs. Its not for outlining design decisions. You also don't need to
explain how the method works. It's a black box.

Your ide can be configured to show warnings if your comments don't match your
parameter list. Though generally you don't change the external api of your
code once you've written it. Or else you then have to update all the methods
that call it.

------
thegreenroom
so your using function names instead of comments?

~~~
martinnormark
You could say that. What I'm saying is that splitting up a function into
smaller functions with good names, is way better documentation than comments.

~~~
pan69
How do you write unit tests for classes like this? A lot of reflection I
assume?

~~~
martinnormark
I only test against the final result, that I expect any public method to
produce. The unit test should pay no consideration to the implementation
details such as private methods.

If you want to test the fragments in isolation, split it out into a separate
class that you use as a dependency. Your desire to do so is often a good
indication that you should split up the responsibility.

~~~
joshka
[https://gist.github.com/joshka/54548c3dfb9a4ebcdea9](https://gist.github.com/joshka/54548c3dfb9a4ebcdea9)

