The Best Code Documentation ‘Tool’ Ever Made
martinnormark.com
The Best Code Documentation ‘Tool’ Ever Made
1–8 of 8 posts
Re: The Best Code Documentation ‘Tool’ Ever Made
#2so your using function names instead of comments?
Re: The Best Code Documentation ‘Tool’ Ever Made
#3so your using function names instead of comments?
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.
Re: The Best Code Documentation ‘Tool’ Ever Made
#4so your using function names instead of comments?
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.
I can confirm this. Function names tend to be much more reliable than comments. Here's an example from Java that can lead to security problems. Consider setSeed from java.security.SecureRandom:
/**
* Reseeds this random object. The given seed supplements,rather than
* replaces, the existing seed. Thus, repeated calls are guaranteed
* never to reduce randomness.
*/
synchronized public void setSeed(byte[] seed) {
secureRandomSpi.engineSetSeed(seed);
}
Unsurprisingly, some implementations of java.security.SecureRandom follow the comment, others follow the method name - causing a potential security issue. To complicate things further, note that the comment in the equivalent Android class java.security.SecureRandom requires setSeed to set the seed, see: http://developer.android.com/reference/java/security/SecureR...
Thus, security libraries implementating of java.security.SecureRandom cannot implement both, the Oracle and the Google version, at the same time in accordance with the specifications. This could have been avoided if the time spent on commenting setSeed would have been spent on finding a better method name.
Re: The Best Code Documentation ‘Tool’ Ever Made
#5The 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.
Re: The Best Code Documentation ‘Tool’ Ever Made
#6Re: The Best Code Documentation ‘Tool’ Ever Made
#7Earlier quoted context omitted.
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.
How do you write unit tests for classes like this? A lot of reflection I assume?
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.
Re: The Best Code Documentation ‘Tool’ Ever Made
#8Earlier quoted context omitted.
How do you write unit tests for classes like this? A lot of reflection I assume?
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.