Francisco Tolmasky gave a talk at #jsconf on Socratic: Documentation Done Right. He asked for feedback and he got me thinking about the problem that coders documentation does not even help them when they go back to it. Ever have that happen with your documentation? Go back to your source comments three months later and they don't make much sense?
The process of coding involves variable and method names which are suppose to be meaningful. A convention has evolved where methods should be verbs because they do something and variables are nouns. Roughly.
So I suggested to Francisco that perhaps Socratic could use Verbalization to verify that methods are verbs. Think of Verbalization as a spell check of only verbs. Maybe it could check that "is" methods are boolean and perhaps more. I suppose the Nounization could be done on variables.
One theme at JSCONF is running JavaScript on client and the server. For example, same validation method on both. This got me thinking about the documentation divide. So why not run Verbalization on both Socratic and Textmate or your IDE. As you build out your code check that your method names are verbs. And this gets you a glossary? So a common plug system for both Socratic and IDEs would be good.
Just a thought or two with a lot more to think about.
No comments:
Post a Comment