As any taught Software Engineer knows how important Documentation for good software projects is. Could you show me best practices for assure good documentation beside of JavaDoc comments?
In my opinion the documentation should not only contain javadoc comments to assure good human readable text for future and present programmers.
My thought would be to assure maybe some paper or wiki. Is there maybe any Software that helps recording documentation beside the standart solutions like JavaDoc, etc.
1
There is a lot of information that could be considered “documentation”. Here’s my summary, with some best practices for each:
-
Class, method, function, and variable names. This is critical to having readable code. All other documentation can easily get out of date, but the text that the compiler actually compiles almost by definition cannot. It is the ultimate reference to what the software does, and good naming should be a priority here.
-
In-line comments. Within functions and methods, having good comments to separate functional sections and explain tricky algorithms are valuable. Make sure they don’t go out of date.
-
JavaDoc-style comments. These are great for generating web pages for easy perusal of a stable codebase, but can be of limited value with code in active development. They are best created and elaborated after code stabilizes, especially for code that is used systemwide. They are less valuable for code used in only one place.
-
Developer documentation. This includes guides for getting started developing the software (packages to install, build procedures, debugging tips, coding styles, etc.). This is valuable when you first start a project (or return to it after an absence), but is seldom used at other times. In a pinch, this information can be obtained from other team members.
-
User/Administrator/Operator documentation. This includes information about how to install, administer, and use the software. Customers value this when they are having trouble, so it should be good. Ideally, the software should be self-explaining, but sometimes that is not possible or appropriate. This should be written by someone with good writing skills.
All these kinds of documentation contribute to the value of the software, but of the five groups, I would say that 1 and 5 are the most important, and 3 is the least important. Unfortunately, except for 3, I know of no software (beyond text editors) to facilitate generating the documentation in question. There are lots of good books about documentation and writing high-quality code in general. One of my favorites is Code Complete.
JavaDoc documentation may be more or less detailed. For example, the inline documentation (in .NET, similar to JavaDoc) is pretty verbose on one of the projects I’m working on, containing not only the description of a method, but also the list of possible exceptions, the examples showing how to use a method (with demo source code in comments), etc.
Having even verbose inline documentation is a good thing, but don’t forget that:
-
Many things cannot be described in source code (and documentation in source code files). What about:
- Security concerns?
- Instructions about how to deploy the project?
- Details about the environment?
- Style guidelines?
- etc.
-
Good inline documentation is a good thing, but this is not an excuse to avoid writing good, readable code. Especially, think about ways the code can be improved in order to avoid explicit documentation. For example, .NET has code contracts which increase the clearness of the code while ensuring that the contracts will never (or rarely) be outdated.
Why?
The best documentation is clearly-written code with an obvious purpose and process. Comments to explain what is being done are then superflous. Comments to explain why the code exists are useful, if not obvious from context.
The underlying question is: what is the purpose of the documentation you have in mind?
Documentation for its own sake may be a waste of effort.
2