Documentation As Your Legacy

Based on hearsay, developers hate documentation…until they come across a project with no documentation!

As you leave your company, how do you want to be remembered? Let me put it this way, if the next programmer is a serial killer that has to review legacy code that you wrote, would you want him to know where you live? Once I thought following a zero comment policy as good because classes, methods, variables should be human readable and obvious, however, there will always be someone who complains about the lack of comments and that your documentation is overwhelming. So, comment sparingly, but when you comment, complement the existing code and comment specifically business reasons behind your code. It’s also useful to use tools in your IDE that automatically apply comments to properties and classes. This is important, but if you comment every object, please don’t leave the default auto-generated comments in there, as they are just as useless as no comments. Finally, you should always reference your code classes to the user-friendly documentation in some other system (such as Confluence). If you comment your code where appropriate and also provide documentation for all your code, then you will be appreciated long past your stay.

Advertisements