Documentation Friday!
Let's face it fellow programmers, we don't document our code like we really should. Why should we? It doesn't add to the functionality of the application so why waste time? Also, it's not very exciting! It's not exciting to type something, run the application and nothing has changed; nothing is visually or functionally different. We just typed something for the hell of it. Wrong!
Why document?
There are many reasons to document. From IDE picking up the documentation for function signature help (such as IntelliSense) to application maintenance. Three months down the road, are you going to remember what the code is doing let alone two years when you have to come back to the application? Someone else helping you with the project going to understand what your piece of code is doing? It's great when someone types code and types a period and the IDE tells him/her what members (properties, methods) are available.
We're humans. Reading sentences about what something is doing can go a long way to describe what's going on. Should you always have to dive into the code? No! You can use many different documentation systems that can read your documentation and create a web site. I personally use JSDuck for my Ext JS and Sencha Touch applications. Even when developing I check the Ext JS api docs for that method I know is there just can't remember what it's called or if it's plural or singular. Documentation can help you and your present and future team develop faster.
When to document
Technically, we should be documenting while we write the code. Comments mixed within the code or block comments to describe what arguments a function can accept. The code itself can provide documentation so that when someone is reading the code the variable names are descriptive. I'll be honest, I've developed applications and while programming think that I should write some documentation about it but don't do it. Then couple months later have to go through and document things and not remember what the heck I was thinking. Kind of just shot myself in the foot right?
Documentation Friday!
Throughout the week you kicked some code butt! What a great week we had! Did we write documentation? No, we kicked code butt! Just look at it! It's fantastic! And it is fantastic. Now we have to rely on #DocumentationFriday where we stop development to go back through and document everything. Not really an agile approach to documenting but it seems to work for me. Code throughout the week and go back through and document everything to close out the week. For me, it's a great way to wind down from the manic development throughout the week and ease into the weekend. Come Monday, game on!
