Dynamics AX Development and Customization Best Practices- code comments

In previous article we have covered coding best practice for Naming conventions and I this article we will cover the best practice guidance for writing code comments.

  • Comments should be used to describe the intent, algorithmic overview, and logical flow.
  • Provide comments so that someone other than the original developer can understand the behavior and purpose of the code.
  • As a best practice, most code has comments reflecting the developer’s intent and approach for the code.
  • Use comments liberally.
    • Include comments that indicate who made the changes.
    • when the changes were made,
    • Why the changes were added.
    • What the changes you do.
  • Comments are particularly beneficial when multiple parties are involved in modifying and maintaining code.

Developers should follow the following guidelines for writing code comments:

  • Do not use comments that repeat the code.
  • Do not use multi-line syntax, /* … */, for comments. Single-line syntax, // …, is preferred, even when a comment spans multiple lines.

Example:

public int getSum()

{

;

// This comment spans multiple

// lines because it has

// a lot to say. The use of

// multi-line syntax is

// not allowed.

}

  • Do not place comments at the end of a line, unless the comment is very short. In most cases, comments should be placed above the code.

Example:

public class ArrayList

{

int count; // -1 indicates uninitialized array

}

  • Remove TODO comments well in advance of a release.

Example:

// TODO: The TODO comments should start with TODO.

Comments should not include:

  • Dates
  • Names
  • Aliases
  • Version or layer references
  • Bug numbers – unless it is a workaround, or unless the code could appear inappropriate if you didn’t know that it was for a bug fix.
  • Politically or culturally sensitive phrases
Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s