Jump to content

Check out our Community Blogs

- - - - -

Source comments: A dialog through time

Posted by gregwarner, 14 April 2011 · 378 views

If you could hold a conversation with yourself from the future, would you do it?

That's largely what it feels like when I'm documenting my source code with comments. I'm a huge believer in documentation, almost to a religious degree. Sometimes, such as now with my current project, I'm faced with a challenging problem that I don't quite have the solution for yet. It's difficult to visualize how I'm going to work this out, so I'll abandon the code, jump up to the top of my class definition, and begin with a slash-star.

I'll just start typing whatever comes to mind. It doesn't have to make sense, it's just my attempt to describe what I'm thinking so far. I'll talk very frankly with myself, showing what I've done, explaining the purpose behind this class, and explaining the difficulties and challenges I'm facing. My documentation is imbibed with a heavy conversational tone.

It's easiest to solve my problems after I've had a night to rest and get away from it. Tomorrow I'll come back and, having slept since the time I wrote that documentation, find myself with a note written by my younger self in the past. (Albeit only a day in the past.) My future self will have fresh perspectives and interesting ideas to try in regards to solving the problem.

I always admire the knowledge and wisdom of a more experienced coder, and sometimes, that coder is my future self. Sometimes, it's best just to ask yourself for help and come back tomorrow.

  • 0

"Once we accept our limits, we go beyond them." -- Albert Einstein.
    • 0
Recommended from our users: Dynamic Network Monitoring from WhatsUp Gold from IPSwitch. Free Download