Re: AWS Coding Styles (and about boring plain-linear text files in the end)

["Yannick Duchêne (Hibou57)" <yannick_duchene@yahoo.fr>]

Le Tue, 18 Jan 2011 20:47:26 +0100, Adam Beneschan <adam@irvine.com> a  
écrit:
> Maybe that's what the style guide author intended.  If so, I think he
> had it completely backward.  Look at the RM's descriptions of what the
> subprograms in language-defined packages do, and then try to figure
> out how to describe them without referring to parameter names.  Try
> Ada.Strings.Unbounded.To_String and To_Unbounded_String, for example,
> in A.4.5(78-79).  That's just the first thing I went to when I picked
> an Annex A section more or less arbitrarily---I didn't have to hunt
> for the "best example".  Anyway, you *could* rewrite the description
> in a way that doesn't refer to the parameter names, but all you gain
> is verbosity and stilted-sounding language---at the expense of
> clarity, readability, and several dozen of your readers' brain cells.
This raise (one more time) the question of comment consistency with  
source. We really need a standard convention to mark program identifiers  
in comments (and corollary to precisely define scope of comments).

-- 
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour  
les chiens.

“I am fluent in ASCII” [Warren 2010]