Code documentation generators (free tools)

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.

C/C++

Doxygen

Screenshots of doxygen documentation:

HTML:

Screen Shot 11-12-17 at 05.57 PM

Latex:

Java

Javascript

C#/VB

  • Sandcastle Help File Builder (SHFB)
    • https://github.com/EWSoftware/SHFB
    • A standalone GUI, Visual Studio integration package, and MSBuild tasks providing full configuration and extensibility for building help files with the Sandcastle tools

    • Screen Shot 06-07-17 at 10.54 AM

 

Advertisements

Code Smells detectors

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.[1] According to Martin Fowler, “a code smell is a surface indication that usually corresponds to a deeper problem in the system“.[2] Another way to look at smells is with respect to principles and quality:[3] “smells are certain structures in the code that indicate violation of fundamental design principles and negatively impact design quality“.

Common code smells include:

  • Class-level smells
    • Large class, Feature envy, Inappropriate intimacy, Refused bequest, Lazy class/freeloader
  • Method-level smells
    • Too many parameters, Long method, Excessively long identifiers, Excessively short identifiers, Excessive return of data
    • Excessive use of literals, Cyclomatic complexity, Downcasting
    • Orphan variable or constant class
    • Data clump

Code Smells detection tools

Some free code smell detection tools (which perform static code analysis) include:

Conclusion

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.

You can research more tools at https://en.wikipedia.org/wiki/List_of_tools_for_static_code_analysis

References

Project management anomalies: Death March

Some situations are often so common that they get a name. A friend of mine pointed me to this interesting Wikipedia article describing a “Death march” during a project:

In project management, a death march is a project where the members feel it is destined to fail, or requires a stretch of unsustainable overwork. The general feel of the project reflects that of an actual death march because the members of the project are forced to continue the project by their superiors against their better judgment.

(quote from Wikipedia)

It is creepy to find that some real-life situations are so common that they already have creepy names.