Tobias C Rittweiler wrote, On 20/06/10 10:13 PM:
> "This represents" does not add any descriptive value, so I'd
> rather never write it for reasons of conciseness. Yet having
> some comments start capitalized, some not, doesn't strike
> me, personally, as aesthetically pleasant.
> The rule is in place (at least fsvo formally), so I'll try
> to remember to stick to it in future, but I'm wondering why
> was it chosen this way?
Coincidentally, a few minutes before I read this, I happened to be
looking at Sun's Java API comment style guide at
where they specify something similar, at least for the @param comments.
The reasoning seems to go like this: As you said, "This represents" does
not add any descriptive value. Their guidelines say "in general, start
with a phrase and follow it with sentences if they are needed."
Their capitalization rules say to start a phrase with lower case and do
not end it with a period (full stop) unless it is followed by a full
sentence. They also say that "If you prefer starting with a sentence,
capitalize it and end it with a period." And "When writing multiple
sentences, follow normal sentence rules."
I'm not promoting their style over any other, just pointing to it as an
explanation: Capitalization and punctuation distinguish between full
sentences and phrases; phrases are preferred for succinctness; sentences
are allowed where necessary.