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. */Read more about this topic: Comment (computer Programming)
Famous quotes containing the word styles:
“There are only two styles of portrait painting; the serious and the smirk.”
—Charles Dickens (1812–1870)
“For the introduction of a new kind of music must be shunned as imperiling the whole state; since styles of music are never disturbed without affecting the most important political institutions.”
—Plato (c. 427–347 B.C.)
“The gothic is singular in this; one seems easily at home in the renaissance; one is not too strange in the Byzantine; as for the Roman, it is ourselves; and we could walk blindfolded through every chink and cranny of the Greek mind; all these styles seem modern when we come close to them; but the gothic gets away.”
—Henry Brooks Adams (1838–1918)