[vc_row][vc_column][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” target=”_self” animate=”false” animation_type=”ghost” color=”black” size=”small” shape=”rounded” type=”ghost” hover_normal=”fill” hover_ghost=”screen” link=”http://casthighlight.wpengine.com/category/product/indicators-methodology/code-insights/software-agility/embedded-documentation/” 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

[/vc_column_text][vc_column_text pl=”0″ pr=”0″ pt=”0″ pb=”0″]

Commented code lines rate is the percentage of lines of codes that are preceded with at least one line of comment. Comments are essential in every programming language for summarizing, communicating and clarifying sections of code – in order to assist others working on an application.

[/vc_column_text][vc_empty_space height=”6px”][vc_column_text pl=”0″ pr=”0″ pt=”0″ pb=”0″]

Low commented code lines can cause readability and collaboration issues among developers, which increases development time and effort.  When done properly, commenting can help maintain code expansions and help find bugs faster.

[/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

A low rate of commenting within an application increases the difficulty that different developers and different teams face when writing new code, since it takes more effort to interpret and modify existing code (this includes external clients who might need to interact directly with an API or otherwise). It also hurts development speed since comments also serve to guide the debugging process.[/vc_column_text][vc_empty_space height=”32px”][nz_btn text=”Cost” target=”_self” animate=”false” animation_type=”ghost” color=”green” size=”small” shape=”rounded” type=”normal” hover_normal=”opacity” hover_ghost=”fill” link=”http://casthighlight.wpengine.com/category/product/indicators-methodology/cost/” icon=”icon-office”][nz_btn text=”Time / Effort” target=”_self” animate=”false” animation_type=”ghost” color=”blue” size=”small” shape=”rounded” type=”ghost” hover_normal=”fill” hover_ghost=”screen” icon=”icon-clock”][/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

CAST recommends establishing an internal standard for code commenting. Ensuring that each application and their corresponding development team has a unified style guide, in order to standardize the type and commonality of comments.
[/vc_column_text][vc_empty_space height=”6px”][vc_column_text pl=”0″ pr=”0″ pt=”0″ pb=”0″]

Developers and project leaders should think about what portions of their codebase may require effort to understand and make appropriate, meaningful additions.  Nonetheless, they should avoid superfluous additions to sections that are self-explanatory. And finally there should be an emphasis on writing comments alongside the development process, rather than after the fact.

[/vc_column_text][/vc_column_inner][vc_column_inner width=”1/2″][vc_column_text pl=”0″ pr=”0″ pt=”0″ pb=”0″ color=”#dd3333″]

References

https://en.wikipedia.org/wiki/Comment_(computer_programming)

https://www.cs.utah.edu/~germain/PPS/Topics/commenting.html[/vc_column_text][nz_btn text=”Style Guide” target=”_self” animate=”false” animation_type=”ghost” color=”turquoise” size=”small” shape=”rounded” type=”ghost” hover_normal=”fill” hover_ghost=”screen” link=”https://github.com/Kristories/awesome-guidelines” icon=”icon-book”][/vc_column_inner][/vc_row_inner][vc_separator color=”grey” align=”align_center” style=”” border_width=”” el_width=””][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 computes the formula below after being uploaded on the portal:

(Nbr_CommentsBlocs / Nbr_LinesOfCode) * 100

Nbr_LinesOfCode:
The total number of lines containing code items (syntax, string).
Blank lines, comments and docstring are excluded

Nbr_CommentsBlocs:
Total number of comment blocs.
A Comment bloc is a set of contiguous lines containing comment, or docstring, and no code items.
Inlines comments count as a bloc.[/vc_column_text][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″]

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