I’m sure you have heard over and over about how important documenting your code is. There are many articles out there on it (just Bing/Google “Software Documentation”). Additionally if you went to school for programming like I did you probably had a professor or two that would give you a lower grade for improper documentation or have a manager/team lead that points it out during peer reviews (thank you Tom!).
Any place that that writes internal software usually has guidelines for what to put in your documentation. However there are many more that don’t and practice the belief of “Good Programmers always use documentation”. While for some programmers this is true but for many it is a myth to think that about them. I know some great software developers in my local area and I know of only a few of them that I can absolutely say they constantly produce good software documentation.
Having had to fix, refractor, create and then months or years later return to that code and have to edit it again I’ve felt first had my own pain of not having documentation in my own code properly the first time around. Of course it is easier to get up to speed again on what was going on as I wrote it myself originally and it was easier to re-remember what I did. However that pain is even worse when you have never seen the code you are now tasked to change.
Another pain point I’ve felt was seeing code that had poor documentation. Honestly I believe that this can be just as bad if not worse having none at all. Many times I have opened up some code and seen something like this at the top of the file:
“Updated stuff that I have been kind of working on all week…”
Yes that is a real comment I’ve seen in the boiler plate header of a very large class that was built for handling intricate business logic. No other comments with in the class that marked the places changes were made!
The point I’m trying to make here is that regardless of the standards (or lack thereof) in place where you work you should get in the habit of keeping your own personal standard of software documentation. I as well as others can attest that in the long run it will save time and headaches when you or others revisit your code. Even if you never touch the code again and it sits in a repository for years after you leave your current work place it will still benefit the next person who looks at it. I can attest to this from personal experience.
Freshly out of school I was tasked to review and document old projects that were sitting out in source control that where created years prior but never use. The internal documentation on some of them allowed me to actually update and put them to use later on because they save us from creating the same software again from scratch. The code that wasn’t documented was never used and was removed in the end because we didn’t have the bandwidth to sit down and comb through it to see what it actually did beyond the basic hint the folder names gave.
So now that I’ve talked about it here are some basics that I think you should get in the habit of when it comes to documentation within your code (Mainly for .Net Projects but this can be done in other languages too):
1. Class Boiler Plate Headers
- Copyright (if needed)
- Full Namespace(.Net)/Package(Java)
- Description of Purpose
- Revision History (In Brief: Date, Who, What was done and where in the class it was done at)
2. If ASP/Form page does not have code behind
- Mimic the Class Boiler Plate Headers above but in HTML Comment format
3. Public Methods
- Summary
- Parameter – Type and what for (if params are passed into method)
- Return – What it will return to the caller
- Remarks – Brief explanation of what it is trying to accomplish
4. Private Methods
- At least one sentence on what it is for and how to use it.
5. Custom created Data Types (Strucs, Enums, ect)
- What they are for and how best use of them
Keep in mind even though you have put in this documentation it can still fail you in the future. Why? Because just putting it in is not enough. You also have to do upkeep on it as well when you make changes. Just like proper upfront research when building requirements for new projects it will make life easier in the future with the extra time you take in doing it.
In closing I want to add a few things for you to think about if you work in an environment that does not have documentation standards in place:
- Just start doing it on your own and document it. Make sure you document how to put in place not just what and why you are doing it.
- Discuss it with the rest of your team and manager/team lead. In my current position and last the managers wanted to put things in place but never had the time to enforce the practices or develop the new plans to pass on to the team.
- Research and create templates for others to use. Never under estimate the power of people not do something because it takes extra time. Even if you can’t programmatically have it pre-written into the code a person is more likely to use something they can copy and paste in over typing it out.
In the end if you do this many people with silently thank you down the road for taking the time to properly documenting your code. I know I do.
