Re: documentation style - 2nd/3rd person tense for function comments

[Steve Litt <slitt@...>]

On Tue, 27 Mar 2012 08:42:01 +0200
steve donovan <steve.j.donovan@gmail.com> wrote:

> On Tue, Mar 27, 2012 at 3:04 AM, David Manura <dm.lua@math2.org>
> wrote:
> > Should comments for Lua functions be written in the 3rd person
> > declarative or 2nd person imperative?
> 
> Funny, I've never been aware of the tense of doc comments, perhaps if
> we used Latin it would have been more obvious ;)
> 
> As with all questions of style: be consistent.  Inconsistencies bother
> people on a subliminal level.
> 
> steve d.
> 

I think the operant question is whether you're describing a stretch of
code, or whether you're giving the next programmer tips. For the former
I'd do something like:

-- #########################################
   FUNCTION do1page() ASSEMBLES AND TRANSLATES ONE PAGE
-- #########################################

For the latter I'd do something like this:

-- #########################################
   BE *SURE* TO CHANGE FUNCTION foo() WHEN CHANGING 
   THIS FUNCTIONS markcount!
-- #########################################

They can be mixed:

-- #########################################
   FUNCTION do1page() ASSEMBLES AND TRANSLATES ONE PAGE
   BE *SURE* TO CHANGE FUNCTION foo() WHEN CHANGING 
   THIS FUNCTIONS markcount!
-- #########################################

That's how I do it anyway.

SteveT