[vc_row][vc_column width=”1/1″][nz_btn text=”Software Agility” link=”http://casthighlight.wpengine.com/software-agility/” target=”_self” animate=”false” animation_type=”ghost” color=”black” size=”small” shape=”rounded” type=”normal” hover_normal=”fill” hover_ghost=”fill” icon=”icon-dashboard”][nz_btn text=”Embedded Documentation” link=”http://casthighlight.wpengine.com/category/product/indicators-methodology/code-insights/software-agility/embedded-documentation/” target=”_self” animate=”false” animation_type=”ghost” color=”black” size=”small” shape=”rounded” type=”ghost” hover_normal=”fill” hover_ghost=”fill” icon=”icon-code”][vc_empty_space height=”12px”][vc_row_inner][vc_column_inner width=”1/2″][vc_column_text pl=”0″ pr=”0″ pt=”0″ pb=”0″]

Why you should care

Ensuring your application source code is well-documented is a no brainer and an undisputed good programming practice. And since applications are now more and more exposed to a technical audience through APIs, the level and quality of the technical documentation is a key differentiator that could make your software adopted (or not) by a user community. The Java-native javadoc (XMLDOC for C#) feature is one of the greatest ways to automatically build your API/technical documentation (see tools like Swagger, SpringDoc, NDoc or Sandcastle) and to ensure it is synced with your code.[/vc_column_text][/vc_column_inner][vc_column_inner width=”1/2″][vc_column_text pl=”0″ pr=”0″ pt=”0″ pb=”0″]

Business Impacts

When proper documentation is attached to an application via documentation generators, the source code becomes much easier to understand and maintain for internal developers.

Without this addition, it may be harder for developers to collaborate on a codebase AND if the application is ever opened for external use, it may be perceived as undesirable, since it would be difficult to work with missing pieces of documentation.[/vc_column_text][vc_empty_space height=”32px”][nz_btn text=”Cost” link=”http://casthighlight.wpengine.com/category/product/indicators-methodology/code-insights/software-resiliency/” target=”_self” animate=”false” animation_type=”ghost” color=”green” size=”small” shape=”rounded” type=”normal” hover_normal=”opacity” hover_ghost=”fill” icon=”icon-office”][/vc_column_inner][/vc_row_inner][vc_empty_space height=”12px”][vc_empty_space height=”32px”][vc_single_image image=”5362″ img_link_large=”” img_link_target=”_self” img_size=”full” alignment=”none”][vc_row_inner][vc_column_inner width=”1/2″][vc_column_text pl=”0″ pr=”0″ pt=”0″ pb=”0″]

CAST recommendations

Static code analysis tools can help your development teams identify where description tags are missing.  A small effort today quickly turns into big quality tomorrow, especially if you plan to expose your application through an API.
[/vc_column_text][/vc_column_inner][vc_column_inner width=”1/2″][vc_column_text pl=”0″ pr=”0″ pt=”0″ pb=”0″]

References

http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html[/vc_column_text][nz_btn text=”Style Guide” link=”https://github.com/Kristories/awesome-guidelines” target=”_self” animate=”false” animation_type=”ghost” color=”turquoise” size=”small” shape=”rounded” type=”ghost” hover_normal=”fill” hover_ghost=”screen” icon=”icon-book”][/vc_column_inner][/vc_row_inner][vc_separator color=”grey” align=”align_center”][vc_column_text pl=”0″ pr=”0″ pt=”0″ pb=”0″]

How we detect

[/vc_column_text][vc_column_text pl=”0″ pr=”0″ pt=”0″ pb=”0″] This code insight verifies the ratio between the number of method parameters which have an associated javadoc (or XMLDOC for C#) tag (e.g. @param name description) and the total number of method parameters.
[/vc_column_text][vc_empty_space height=”12px”][vc_row_inner][vc_column_inner width=”1/1″][vc_single_image image=”5362″ img_link_large=”” img_link_target=”_self” img_size=”full” alignment=”none”][vc_column_text pl=”0″ pr=”0″ pt=”0″ pb=”0″]

About CAST and Highlight’s Code Insights

Over the last 25 years, CAST has leveraged unique knowledge on software quality measurement by analyzing thousands of applications and billions of lines of code. Based on this experience and community standards on programming best practices, Highlight implements hundreds of code insights across 15+ technologies to calculate health factors of a software.

[/vc_column_text][vc_empty_space height=”16px”][nz_btn text=”See Features” link=”http://casthighlight.wpengine.com/outputs-analytics/” target=”_self” animate=”false” animation_type=”ghost” color=”black” size=”small” shape=”rounded” type=”normal” hover_normal=”fill” hover_ghost=”fill” icon=”icon-stats”][nz_btn text=”How it works” link=”http://casthighlight.wpengine.com/how-it-works/” target=”_self” animate=”false” animation_type=”ghost” color=”black” size=”small” shape=”rounded” type=”ghost” hover_normal=”opacity” hover_ghost=”fill” icon=”icon-cog”][/vc_column_inner][/vc_row_inner][/vc_column][/vc_row][vc_row][vc_column][vc_column_text]

[/vc_column_text][/vc_column][/vc_row]