Source Code documentation is an often neglected aspect of Software Engineering. In most software projects, an overview of the code structure is useful both for new developers looking at the code for the first time, as well as a reference for all developers interacting with this code.
Fortunately, there are many useful tools to help us with this issue, namely, Code Documentation Generators. These tools pick up the code’s structure through syntactic parsing and typically augment it with information supplied by the developers directly in the source code. In the last step, a nice HTML-based reference manual is typically exported.
The following sections present some interesting examples of this type of tool.
“Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some extent D.”
A Code smell is an interesting Software Engineering concept. According to Wikipedia, a Code Smell
“refers to any symptom in the source code of a program that possibly indicates a deeper problem. According to Martin Fowler, “a code smell is a surface indication that usually corresponds to a deeper problem in the system“. Another way to look at smells is with respect to principles and quality: “smells are certain structures in the code that indicate violation of fundamental design principles and negatively impact design quality“.
NOTE: StyleCop works with source code, whereas FxCop works with compiled files
Most of these smells lower your code’s quality and maintainability. Be sure to include some of these detection tools on your development processes, as well as appropriate coding standards. Automatic noncompliance detection can be accomplished by adding these tools to your build process.