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:
“... it is use, and use alone, which leads one of us, tolerably trained to recognize any criterion of grace or any sense of the fitness of things, to tolerate ... the styles of dress to which we are more or less conforming every day of our lives. Fifty years hence they will seem to us as uncultivated as the nose-rings of the Hottentot seem today.”
—Elizabeth Stuart Phelps (1844–1911)
“Can we love our children when they are homely, awkward, unkempt, flaunting the styles and friendships we don’t approve of, when they fail to be the best, the brightest, the most accomplished at school or even at home? Can we be there when their world has fallen apart and only we can restore their faith and confidence in life?”
—Neil Kurshan (20th century)
“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)