Strict Standards: call_user_func_array() expects parameter 1 to be a valid callback, non-static method GoogleSitemapGeneratorLoader::Enable() should not be called statically in /home/bombmin/bombinator.com/gamedev/wp-includes/plugin.php on line 164
Bombinator Game Development <br /> <b>Deprecated</b>: preg_replace(): The /e modifier is deprecated, use preg_replace_callback instead in <b>/home/bombmin/bombinator.com/gamedev/wp-includes/formatting.php</b> on line <b>82</b><br /> » documentation

Posts Tagged ‘
Deprecated: preg_replace(): The /e modifier is deprecated, use preg_replace_callback instead in /home/bombmin/bombinator.com/gamedev/wp-includes/formatting.php on line 82
documentation’

You’re Doing It Wrong: Automating Documentation

Wednesday, June 18th, 2008

Deprecated: preg_replace(): The /e modifier is deprecated, use preg_replace_callback instead in /home/bombmin/bombinator.com/gamedev/wp-includes/formatting.php on line 82

I recently came across the article Automation for the people: Pushbutton documentation at IBM developerWorks. Let me start out by saying I am a fan of automation and that automating the creation of source code documentation, user documentation, and build diagrams is fine in my book. What annoyed me was the automated creation of UML and entity-relationship diagrams. Scratch that, it wasn’t the automated creation of them, because that can have its uses, it was the implication that the creation of these diagrams was tangential to development and so we should just write the code and generate the docs.

UML and entity-relationship diagrams help us develop code. If you find that they need to be changed at the implementation stage then you should go back (as painful as it may seem) and fix the problem at the design stage. In the long run you’ll be much better off. I can hear people complaining already in that I am not following my own advice and following good design practices for the snake game, and they are right. However there is a difference in that the snake game is just something I’m doing to explore Haxe. So I want the flexibility to change the design as I learn the language and its features. If this were a serious project you bet I would be following good process.