|
Sponsored Links
Resources
.NET Research Library
Get .NET related white papers, case studies and webcasts
|
News
News
News
|
Messages: 10
Messages: 10
Messages: 10
Printer friendly
Printer friendly
Printer friendly
Post reply
Post reply
Post reply
XML
XML
XML
|
 |
Try "Literate Programming" in .NET with NLiterate
Another CodeProject project, NLiterate, explores the "Literate Programming Style" championed by Donald Knuth for so many years. Believing that documentation should be a formal part of programming, NLiterate creates a strong connection between code and comments that compilers can guarantee and enforce.
From the website:The literate programming style developped by the mighty D.Knuth consists of writing source code and documentation togheter in the same file. A tool then automatically converts the file into both a pure source code file and into a documentation file with pretty-printed source code. The litterate programming style makes it easier to ensure that the code examples in the book/documentation really compile and run and that they stay consistent with the text. Check out the NLiterate home page.
|
|
|
Message #119196
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Oh. My. God
[Disclaimer - this post specifically ignores the case for documenting black-box API libraries, in which clear, concise documentation is usually desirable].
Look, Knuth is a genius and everything, but Literate Programming as he would have it was never a good idea. This tool makes programs anything but literate (or legible). It completely overshoots the twin goals of readability and maintainability:
/// <para>
/// The length of the string is accessed through the <see cref="Length"/> property:
/// </para>
/// <code id="properties" title="Length Property">
/// public int Length
/// {
/// get{return this.data.Length;}
/// }
/// </code>
How on God's earth is this any easier to read and understand than this:
public int Length
{
get { return this.data.Length; }
}
I appreciate that the examples given are just that, but I can't think of any situation where I would prefer a mixture of code and documentation over LITERATE CODE.
Even worse (if it could get any worse) is that this mechanism makes any IDE worthless. Where's my code completion? Where's my highlighting? Where's my refactoring support? Oops.
If you think your code is too hard to understand without comments then fix the code. Whenever you find yourself typing "this method does this", why not rename the method to describe its purpose? Whenever you find yourself typing "//f is the frequency of the wavelength", why not rename 'f' to 'frequency'? You will find that the more you try writing code as if you were writing a story, the less you need comments. The big bonus, of course, is that now you have truly executable documentation.
Jim
ThoughtWorks
|
|
|
Message #119241
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Try "Literate Programming" in .NET with NLiterate
It's an interesting concept and at first glance it sounds like something to consider. But at the end of the day, I agree with the last comment (no pun intended). It is better to use comments for what they are intended...to make clear something that is not.
The overall issue I have with using a "code base" as your "documentation base" is that the two satisfy two different agendas. Your code is a literal artifact of your implementation and (IMHO) your design documentation should discuss overall intent as opposed to literal implementation.
-Mathew Nolton
|
|
|
Message #119388
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Oh. My. God
[Disclaimer - this post specifically ignores the case for documenting black-box API libraries, in which clear, concise documentation is usually desirable].Look, Knuth is a genius and everything, but Literate Programming as he would have it was never a good idea. This tool makes programs anything but literate (or legible). It completely overshoots the twin goals of readability and maintainability:/// <para>/// The length of the string is accessed through the <see cref="Length"/> property:/// </para>/// <code id="properties" title="Length Property">/// public int Length/// {/// get{return this.data.Length;}/// }/// </code>How on God's earth is this any easier to read and understand than this:public int Length{ get { return this.data.Length; }}I appreciate that the examples given are just that, but I can't think of any situation where I would prefer a mixture of code and documentation over LITERATE CODE.Even worse (if it could get any worse) is that this mechanism makes any IDE worthless. Where's my code completion? Where's my highlighting? Where's my refactoring support? Oops.If you think your code is too hard to understand without comments then fix the code. Whenever you find yourself typing "this method does this", why not rename the method to describe its purpose? Whenever you find yourself typing "//f is the frequency of the wavelength", why not rename 'f' to 'frequency'? You will find that the more you try writing code as if you were writing a story, the less you need comments. The big bonus, of course, is that now you have truly executable documentation.JimThoughtWorks Well said. That's why I like one of Marin Fowler's refactorings: "Replace comment with method". I also like the xml comments that VS.NET provides and like the fact that these can be kept in a completely separate file unlike the html javadocs found in java.
-Trevor
|
|
|
Message #119420
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Bad interpretation of NLiterate
Hi,
I am the author of the NLiterate article and I want to make give a "correcting" comment on the remarks above.
For me, NLiterate is mainly a tool to make sure that the EXAMPLES in the documentation compile and are in sync with the source code. I have never meant to write the code directly into the documentation as some comments above thought it was. I guess I will add a paragraph to clarify things on the article.
Regards,
Jonathan
|
|
|
Message #119472
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Bad interpretation of NLiterate
I like the idea of having comments & metadata expressed in XML (given there are tools that ease the process). It is interesting to think of the possibilities of extracting the comments/metadata from the source as separate XML documents. I definitely don't like the source code replicated in the comments either but see this was a mistake.
|
|
|
Message #119728
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Documentation is a must for Framework library
If you are a framework developer, you better make sure that the types defined in your framework have documentation associated with it. .NET Fx codebase is an excellent example for this. You can get the .NET Fx code from the rotor distribution.
Also, nobody said that you have to write documentation along with the code. The guideline is that you should have your code properly documented before shipping it. So, the comments about refactoring and stuff like that aren't quite valid.
|
|
|
Message #119777
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Bad interpretation of NLiterate
I definitely don't like the source code replicated in the comments either but see this was a mistake. How do you instert examples into your documentation ?
|
|
|
Message #120297
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Bad interpretation of NLiterate
That posting appeared to just insert the source code for the method into a comment, not an example usage.
|
|
|
| |
|
| New content on TheServerSide.NETNew content on TheServerSide.NETNew content on TheServerSide.NET |
|
|
Language "mashups" will become more prominent, and developers will become polyglots, one programmer suggests.
SearchWinDevelopment.com offers an introduction to the language, performance, testing and data management improvements in VS 2008.
VBCode.com code snippets cover all aspects of application development, from data binding to security to the user interface.
Get up to date on XAML best practices with a variety of articles, tutorials and webcasts. [SearchWinDevelopment.com]
One team's experience with the VSTS DB edition suggests that it can improve workflow for dev teams. It also enhanced Agile efforts.
(June 24, Article)
Microsoft has begun to include DSL tools in the VSTS kit. A new book by Steve Cook and other VSTS team members helps set the stage.
(June 24, Article)
Cartoon: Be it ever so humble there is no place like your home after you get a Microsoft Home Server .
(June 18, Cartoon)
Microsoft's Thom Robbins says new technology to highlight in NET 3.5 includes AJAX, LINQ for both C# and VB, as well as tooling enhancements intended to ease the task of building WPF, WF and WCF apps.
(June 29, Podcast)
Venkat Subramaniam discusses AJAX bottlenecks, the tenets of Agile development and more. He spoke at the Ajax Experience.
(June 25, Tech Talk)
In the second of a two-part series, Michele Leroux Bustamente discusses design decisions related to the claims-based security model. Read the story and walk through the process for creating a set of claims-based utilities to encapsulate claims authorization at the service tier.
(May 24, Article)
Understanding why the Entity Framework exists and learning where it can fit into your projects can get you prepared for the eventual release early next year.
(May 10, Article)
Resource: This learning guide gives you quick access to useful links on Windows Communication Foundation security information.
(April 24, Article)
TSS.NET's Jack Vaughan spoke recently spoke with Microsoft's Brad Abrams to find out what he is seeing in the field and what the chefs in Redmond are cooking. Along the way he discusses patterns of AJAX frameworks.
(April 11, Article)
In a two-part series, Michele Leroux Bustamente explains how claims-based security is supported by WCF, and how you can implement a claims-based security model for your services.
(March 29, Article)
Windows Workflow Foundation is a new technology that many developers will need to get their heads around. In a brief excerpt adapted from Programming Windows Workflow Foundation: Practical WF Techniques and Examples using XAML and C#, K.Scott Allen considers aspects of workflow definition.
(March 22, Chapter Excerpt)
|
|
