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

[andreas graeper <agraeper@...>]

could s.o. rewrite the 'definition' of #-operand for tables in manual,
instead, for one person (me) please ?
it leaves more holes than a decision for two xor three persons would do.

{1,nil,3,nil,5,nil,...} is of length 1, 3 or 5 (depends on ?)

l={-1,nil,1,nil,3,nil,5}
#l => 7

7 is no n, so that l[n] is not nil, but l[n+1] is.

version 5.1.5

2012/3/27, Steve Litt <slitt@troubleshooters.com>:
> 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
>
>