lucy-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nathan Kurz <n...@verse.com>
Subject Re: [lucy-dev] Markdown for documentation
Date Thu, 31 May 2012 07:41:50 GMT
On Tue, May 22, 2012 at 8:09 PM, Marvin Humphrey <marvin@rectangular.com> wrote:
> On Fri, May 18, 2012 at 11:57 AM, David E. Wheeler
> <david@justatheory.com> wrote:
>> On May 18, 2012, at 2:40 PM, Marvin Humphrey wrote:
>>
>>> reStructuredText is probably a little noisier to read, true.  But at least
>>> they're both quite readable in comparison to HTML, or XML as used in C#
>>> comments:
>>>
>>>    http://broadcast.oreilly.com/2010/06/understanding-c-xml-comments.html
>>>
>>>     /// <summary>
>>>     /// The constructor sets the name, age and cash
>>>     /// </summary>
>>>     /// <param name="name">The name of the guy</param>
>>>     /// <param name="age">The guy's age</param>
>>>     /// <param name="cash">The amount of cash the guy starts with</param>
>>>     public Guy(string name, int age, int cash) {
>>>          this.name = name;
>>>          this.age = age;
>>>          Cash = cash;
>>>     }
>>
>> I am glad you don’t hate the rest of us enough to do something like that. ;-P

I'm not sure if I have the same fear as David, but my fear is pretty
strong here too.    At first, I thought you were talking about the
format for the external documentation, and I was slow to realize that
you were talking about adding all of this to the code itself.  Yikes!

I feel comments should explain the intent of and offer structure to
the code, and not duplicate the information already contained in the
code.  Maybe your examples are just strawmen, but it feels like a lot
of effort for very little gain.  Rather than arguing about how to
format all the boilerplate, I'd like the discussion to be about why we
need it at all.

I found it hilarious that in your linked C# example that the comments
were broken and misleading.   I thought (hoped) at first that this was
going to be the point of the article, but no, it seemed to be just
another cut-and-paste error that illustrates the perils of mandatory
and elaborate commenting strategies.   And even if they weren't
mangled, do these comments add anything to the code?

-------

/// <summary>
/// Read-only backing field for the Name property
/// </summary>
private readonly string name;
...
/// <summary>
/// Read-only backing field for the Name property
/// </summary>
private readonly int age;

-------

Fearing I can't express myself coherently on this, here's a link to the
chapter from Code Complete that echos (and helped create) my
sentiments on comments.  The section "Commenting Routines"
is most on point, but the Socratic Dialog at the beginning is applicable too.
The rest of the book is great too -- read it if you haven't.

http://www.scribd.com/doc/95398523/McConnell-Code-Complete-Chapter-32-Self-Documenting-Code

> Let's consider how various documentation systems, both real and theoretical,
> stack up against the C# XML system according to several criteria.

Fabulous summary of the formatting options though!

--nate

Mime
View raw message