On Thursday, 22 September 2016 at 18:26:15 UTC, Andrei Alexandrescu wrote:



====
Parameters:
r | The range subject to partitioning.

Returns:
Something awesome.
====

This is incorrect because one is not supposed to punctuate sentence fragments as full sentences. Next attempt:

This one. If nothing were ever to follow the fragment, I would go with no caps and no punctuation. As that's not the case, then this is the one. It's acceptable in English writing to break the rules where it flows and improves readability than to force something awkward out of conformity.

On a related note, I recommend anyone who frequently writes (no matter the context -- software docs included) to read Steven Pinker's 'The Sense of Style' [1]. It's practical advice for modern writing that, IMO, does more to destroy Strunk & White (in a respectful manner) than improve upon it. Basically, he dispenses with dogma in favor of practicality.

[1] http://stevenpinker.com/publications/sense-style-thinking-persons-guide-writing-21st-century

Reply via email to