When working on a large project, take the time to document the internals.

So I’m working on a very large project which I intend to discuss elsewhere at a later date. But it involves a lot of code–and is quite easily the largest thing I’ve ever considered taking on to date.

And I find I go for a few weeks making serious headway–then find myself spending less and less time coding and more and more time surfing the web. I think it’s because I’ve hit a roadblock; the project has gotten so large I can no longer see the forest for the trees. (And hell, at the level some of this code exists, I can’t see the damned trees for the individual leaves.)

I’ve discovered a secret, however.


When I start forgetting what’s there, it’s good to stop at a good stopping point, and take a survey of what’s there. Nothing fancy; just a simple iteration of what’s where at a directory level helps worlds to get your bearings.

Because otherwise, it’s easy to get lost when you’re looking at several months worth of work, with over a hundred source files and tens of thousands of lines of code, wondering “what’s next.”

And in the documentation you even find things that perhaps you forgot to deal with. Corner cases you thought “I’ll deal with you tomorrow”–only for tomorrow to never come.

So today’s a documentation day. It’s healthy because it reminds me of what I’ve done. It also reminds me of what I still need to do. And it reminds me of things I could do in the future.

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s