Comment (computer Programming) - Styles

Styles

There are many stylistic alternatives available when considering how comments should appear in source code. For larger projects involving a team of developers, comment styles are either agreed upon before a project starts, or evolve as a matter of convention or need as a project grows. Usually programmers prefer styles that are consistent, non-obstructive, easy to modify, and difficult to break.

The following code fragments in C demonstrate just a tiny example of how comments can vary stylistically, while still conveying the same basic information:

/* This is the comment body. Variation One. */ /***************************\ * * * This is the comment body. * * Variation Two. * * * \***************************/

Factors such as personal preference, flexibility of programming tools, and other considerations tend to influence the stylistic variants used in source code. For example, Variation Two might be disfavored among programmers who do not have source code editors that can automate the alignment and visual appearance of text in comments.

Software consultant and technology commentator Allen Holub is one expert who advocates aligning the left edges of comments:

/* This is the style recommended by Holub for C and C++. * It is demonstrated in ''Enough Rope'', in rule 29. */ /* This is another way to do it, also in C. ** It is easier to do in editors that do not automatically indent the second ** through last lines of the comment one space from the first. ** It is also used in Holub's book, in rule 31. */