I’m just about to finish a marathon 9 month project– a web app with over 70k lines of code. Problem is I hardly used comments, never used javadoc, and never kept any good documentation of any kind. (oh the guilt!! 🙂 )
I now need to focus on the non-technical aspects of my business and pass this giant off to a programming team for maintenance and new features. So what can I do…what are the most useful comments/documentation to write? What’s the best strategy for retroactive documentation? (Are there books on the subject?)
PS. Thanks for your months and months of help Stack Overflow. I barely knew HTML a year ago. You got me through it all!
70K lines isn’t all that large. It might be larger than projects you typically work on, but at least it’s not so large that one person can’t understand most of it. That’s probably what got you into trouble in the first place. It wouldn’t kill you to go through each file and write a few sentences about what the class does.
70K lines is way too large to foist upon someone, or some team, without some sort of explanation of what it does and why. Take pity on your poor underlings (and reduce the man-hours that they’ll waste scratching their poor heads) by at least writing a road map that explains in detail what the project does, how it’s organized, which parts are important for performance or to meet requirements, which parts need work. If you had any written requirements for the project, those should be included.
I’d imagine that before you make your team work on this undocumented pile of code you plan to at least sit down wit the team members for a day and give them an orientation. Write down everything you’d want to tell them during that orientation. Give the team that document and some time to read it before you really do meet with them. Now you can use that day with them to refine the document by answering their questions. Ensure that the answers make it into the next revision of the document. Let your team’s first task be to fix the problem you created. That’ll help them get ready for the time when they do start implementing new features.
Be available to answer questions from the team for the forseeable future. Create some sort of system for organizing and preserving the information you provide. A wiki seems obvious, but you also want to make sure that new questions get noticed and answered quickly. A defect tracking system could work well. So could some sort of Q&A format like SO.
Change your attitude toward documentation. Learn from your mistake, change your ways, and encourage/insist on people spending time to document what they do. Try to make documentation as automatic as possible by connecting your defect tracking system and your version control system. Give your people the resources they need to produce useful documentation. Put someone in charge of documentation.