Thursday, June 7, 2012

Refactoring is the best documentation

I was recently looking at a simple function that provided documentation for a service. The documentation is made up of two parts. The base documentation that all services provide and the documentation for the endpoints that a service specifically provides.

The fact that there was two parts to the resulting documentation seemed a little obfuscated and so I thought that I should add a comment to help explain things. Normally this would be done this way:

However, by refactoring the service specific documentation to a separate method I was able to achieve my goal of documenting what the code was doing with the method name rather than injecting a coupled comment. This also has the benefit of making the code much more readable as well as self documenting. 

No comments:

Post a Comment