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

User Experience (UX) References

Here are some interesting references on User Experience / User Interfaces, which I personally recomend:

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

Domain Specific Languages (DSLs)

Domain Specific Languages (DSLs) are special-purpose programming languages developed for a specific domain. Some of its most interesting benefits include:

  • increasing productivity (by reducing the lines of code that have to be written manually)
  • test generation
  • formal verification

These languages work by using higher-level constructions and restrictions. They can be either textual (declarative or imperative) or graphical, and can include multiple views for the same domain.

I’ve used this type of languages extensively in my work and it saves a lot of time. “Preprocessing” is one of the tyipcal ways to implement them. Some subtypes include:

  • Macro processing
  • Source-to-source transformation (conversion between languages)
  • Pipeline
  • Lexical processing

( more info at http://www.rose-hulman.edu/Users/faculty/young/OldFiles/CS-Classes/OldFiles/csse490-mbse/Readings/DSL-Survey-WhenHow.pdf )

You can use these languages for several purposes, including:

  • Defining an entity model
  • Protocol definition
  • High-level user interface description
  • Automated test case description
  • Software architecture description

Microsoft has some easy to use DSL editor tools in Visual Studio. Check the “Modeling SDK for Visual Studio – Domain-Specific Languages” at http://msdn.microsoft.com/en-us/library/bb126288.aspx .

I strongly recomend using DSLs, they can save you a lot of time and money.

References: