GhostDoc Archives - Page 2 of 7 - Software Quality Blog

4 Reasons Why We Need Code Comments

November 13, 2018Mark HenkeNo Comments

Why do we need code comments? I would not be surprised if your first answer is, “We don’t.”

I get it. Senior developer after senior developer has taught us that “comments are bad.” And we cheerfully nod our heads, saying, “I am smarter for not using them.” We grin smugly when we see one of our juniors make the “mistake” of using comments in their code.

But as much as we sometimes abuse them, we still need comments.

I know comments don’t affect the code’s behavior. I understand how they can get stale and stop making sense. I am all for writing clean code, and I do my best to ensure my variables, methods, and class names describe their intent as accurately as possible. If I see dead code lying around in the comments for a while, I delete it.

But here is the bottom line: we need code comments because there are some things they do better than plain code. Here’s why.

(more…)

Spelling_Errors_Code_Written_in_Child_s_Blocks_Spelled_Wrong

Should You Hold Spelling Errors Against Developers?

October 16, 2018Eric GoebelbeckerNo Comments

You’re checking out some code. It’s been a long time since you looked at this project. Or maybe it’s the first time. You point your editor at an interesting file name and double-click to open it. Your coffee is warm, your mind is clear, and you’re ready to go.

And there it is, sticking out like white socks in sandals. A spelling error.

How do you handle it? Do you fix it? Do you ignore it? Discuss it with the author? Bring it up during lunch when he’s not around?

(more…)

Released: GhostDoc v2018

October 9, 2018Serge Baranovsky2

Note to the GhostDoc v5 users: The v2018 requires a new license code. Users with License Protection or active Software Assurance subscription are eligible for a free upgrade. See the information at the bottom of this post for the details.

The v2018 release is packed with new and exciting features of which one particular is long awaited for – visual editing for XML comments – the?feature that makes XML documentation authoring a breeze!

New features

Visual Editing for XML Comments
New menu and VS command – Document Project – now can generate XML Comment templates for a whole project
Support for C# 7.2 and VB 2017 syntax
The base web help documentation themes are now frameless. Original frame-based themes still shipped under new names
Support for Code Contracts when generating help documentation
Support for the <inheritdoc /> tag – in the XML Comments as well as the generated help documentation
Added VS IntelliSense file documentation output option
Added support for regular expression support in Dictionaries – Summary Override – enables flexible summary generation
New menu and VS command – Document File Header – allows generating/updating the file header without having to re-document the file
Improved performance of the Document File/Type batch actions
Introduced the Bug Bounty program – earn a license for helping us discover and fix bugs
Retired MS Help 2 documentation output format
GhostDoc Community edition now requires a one-time free Community License activation after 30 days of use
There are now two GhostDoc EULAs – Commercial License and Community License

For the detailed list of v2018 changes see What’s New in GhostDoc v2018

To see new features by product edition see this page ? http://submain.com/ghostdoc/editions/

Visual Editing for XML Comments

The number one challenge authoring XML comments, according to our users, has been ensuring a well-formed XML that includes encoding HTML formatting tags, code samples, etc. If that is not painful enough, many of malformed XML issues don’t even show up until the help docs are generated.

And now we offer a solution to this! Visual editing makes it painless to insert tables, lists, pictures, links, source code samples, and other formatting directly in your XML doc comments.

This is a huge leap from plain XML comment maintenance. Now you have WYSIWYG editing and don’t have to worry about valid and compliant XML in your comments. And there is no longer need to look up the correct syntax of the XML comment section tags and format to use.

The visual comment editor allows you to create and edit comments directly within an editable preview of the generated documentation. Comments created with the visual editor are written back to your source code in standard XML format, properly encoded, when required.

You still can have GhostDoc auto-generate your XML doc template in the Visual Editor, and then you have a Word-like experience to continue editing your documentation.

The new Visual Editor is such a great improvement – we also included it with the GhostDoc Community Edition!

Themes are now frameless

We have updated the web documentation themes with a modern frameless design. The new themes also allow for the help documentation search locally not requiring the server side active component. The older frame-based themes are still included for compatibility with the new names.

<inheritdoc /> tag

Instead of copying and syncing the base member XML Comment summary for a type member, using?the <inheritdoc /> tag allows GhostDoc copying the documentation from base members into the final help documentation at the time the documentation is generated hence always rendering the latest copy of the base member docs.

Code Contracts

GhostDoc now will take your Code Contract XML Comment details and render them in the generated help documentation and Visual Editor. GhostDoc supports the following Code Contracts XML elements

<ensures />
<ensuresOnThrow />
<requires />
<invariant />
<pure />

To create the XML Comment tags for Code Contracts, we recommend using the?CodeContracts tools for .NET

New output format – VS IntelliSense file

We added a new documentation output format – the IntelliSense file which is similar to that Visual Studio produces and GhostDoc users can also leverage of all the filtering built-in into the Build Help Documentation dialog as well as can generate it via the command line tool.

The VS IntelliSense format takes place of the MS Help 2 documentation output format that GhostDoc no longer supports.

Document Project and Document File Header

We must never say never – now GhostDoc has a new command to generate XML Comment templates for a whole project – Document Project.

Creating a file header used to be part of the Document File batch command and while it still is, we introduced the Document File Header command that allows generating and updating file header without having to re-document the whole file.

RegEx in Dictionaries – Summary Override

Using regular expressions can enable developers to do simple yet powerful things. Now you can use regular expressions in the Summary Override dictionary to improve the quality of the generated comment templates.

Here are two sample Summary Override entries:

New(?<pattern>(.|\n)*) -?Creates new {pattern}.
To(?<pattern>(.|\n)*) -?Converts to {pattern}.

These will create summary for NewCustomer as “Creates new Customer” and for ToModel as “Converts to Model”.

How do I try it?

Download the v2018 at http://submain.com/download/ghostdoc/

Feedback is what keeps us going!

Let us know what you think of the new version here ? http://submain.com/support/feedback/

Older version licenses

Note to the GhostDoc v5 users: The v5.x license codes won’t work with the v2018. For users with License Protection and active Software Assurance subscription we have sent out the v2018 license codes. If you have not received or misplaced your new license, you can retrieve it on the My Account page. Users without the License Protection or with expired Software Assurance subscription will need to purchase the new version – currently we are not offering upgrade path other than the Software Assurance subscription. For information about the upgrade protection see our Software Assurance and Support – Renewal / Reinstatement Terms

What Are the Biggest Code Commenting Fails You’ve Seen?

September 18, 2018Sylvia FronczakNo Comments

We often focus on code fails. But what else have we seen and done that makes us drop our heads in shame and frustration? What else do we laugh (and cringe) at when reading code? The comments!

Whether they’re redundant, unreadable, confusing, or there’s just no comments at all, we can learn a lot from failure. And to spice things up, I’m going to throw in a biking analogy. You’re not sure if that’ll work? Me neither. But let’s go on this ride together and find out.

(more…)

I’ll Delete Your Commented Code Without Reading It and I’m Not Sorry

July 17, 2018Melissa McEwen1

I was knee-deep in a mess of undocumented legacy code. I wasn’t even sure who had authored this code, but whoever it was, they had long departed to places unknown. The code was in a language I didn’t even really know. And the bug was marked “critical.” If I didn’t fix it, an entire academic department website would display totally incorrect information.

It was then I encountered the “thing.” A large commented out block of important-looking code. Was it left behind by an ancient civilization? Could it help me? Or was it a beast placed into a jail of a comment block to protect innocent coders?

I call this “comment junk,” and my life’s mission is now to delete as many of these trash piles as possible. Here’s how I do it.

(more…)

Taking the Sting Out of Code Documentation

July 3, 2018Melissa McEwen1

It’s a sad fact that code documentation rarely gets the attention it deserves. That’s a shame since it’s often a crucial part of the final product. Bad documentation often makes the difference between how easy it is to fix a bug a year later or whether a customer chooses to integrate with or buy your software.

Many software teams say they don’t have the time or resources to do documentation. I recommend integrating it with the process, but I’ve seen this go wrong way too many times. Erik Dietrich describes projects that required XML doc comments for every single method and class. I was on a project where every story in Jira required corresponding documentation. The developers reluctantly wrote a lot of documentation that we believed no one would ever use. And we were right.

With documentation, it’s key you have a well-developed documentation process. And you should also take advantage of modern tools to save time and identify documentation gaps.

Plan As a Product

Documentation IS a product, even if it’s only used internally. Once you see it as a product, treat it like you do your other products. At the bare minimum, you want to have a collection of use cases to measure the success of the final product. Who is your audience? How will the documentation be used? What information do users need to successfully do these things?

Integrate With Code

Once you have a vision, you should consider tools that save time and prevent duplication of work. No one wants to have to write code and then go into some other system to write documentation. It doesn’t help that the other system is usually a mediocre wiki or content management system.

In 2018, there’s no reason to do this. Modern documentation automation products like GhostDoc save time and help with consistency. GhostDoc can generate code comments automatically from within Visual Studio. With GhostDoc Pro, you can use these to generate help files.

Develop an Editorial Workflow

I know, you’re skeptical of automated comments. You’ve probably seen some pretty baffling documentation that was so obviously autogenerated. That’s why I recommend it as a tool, not as a substitute for a good process.

It’s critical that you have an editorial process as well. Would you push unreviewed code to production? Then why push unreviewed documentation? On my teams, I have documentation go through peer review just like any code does.

GhostDoc has some awesome features for editorial review. You can easily mark and track comments that are auto-generated. That allows reviewers of any kind to find and evaluate them. In my experience, many are good enough, but there are still many that need some additional explanation.

No one likes outdated documentation that doesn’t work. GhostDoc can find documentation comments that are out of sync with the parameters, return types, and type parameters of the associated code.

Review at a High Level

But peer review isn’t enough to evaluate the software overall, and it’s not enough for documentation. Documentation should also be reviewed as a whole. I recommend doing this as a team by having other key stakeholders involved as well.

I also recommend having other non-engineers review documentation. How many developers complain that marketing doesn’t “understand their product”? Well here’s an opportunity to finally write something that helps. The best documentation is usable on some level to marketing, product, project, and sales teams.

Analyze Usage

Many companies do user research for their software. If your documentation is user-facing, consider doing some user research on it. At Write the Docs Portland this year, Jen Lambourne gave a great talk about how their company does user interviews for documentation. She said, “It’s a way to find what works rather than just what’s popular for us.” In the end, you’ll also gain key insights about your product beyond just documentation. Many teams use this research to develop new features, drive marketing, and identify product weaknesses.

Many teams also use traditional user analytics tools like Google Analytics or Pendo. This allows them to capture data on how users find and use documentation.

If the documentation is internal, you still want to have some basic user research. For this, I often do what I call “cross-training.” When I was a (not very) competitive swimmer, we sometimes did cross-training. It was where swimmers would do non-swimming dry-land exercises like running and weightlifting. This increased our flexibility and strength in ways that swimming alone couldn’t.

Use your documentation as a cross-training tool. Have one team review another’s documentation. This reduces the bias toward writing documentation that is too difficult for non-experts. It also builds organizational capacity?now you have more developers in your organization who know your software well.

Support Documentation Organization-Wide

Documentation users and writers are EVERYWHERE in software organizations. Many companies now have practices and working groups for developer tools, culture, and architecture. Why not have one for documentation?

This kind of support signals that you believe documentation is important. It also helps bring together experts to develop best practices and share knowledge. I’ve been in more than one of these groups where people didn’t even know each other before. They didn’t know anyone else in the company did documentation!

The Takeaway

Bad, incomplete, and absent documentation, whether user-facing or internal, is a risk. Great documentation is an asset. If you’re not thinking about documentation, you’re behind.

Take the sting out of documentation by developing a modern documentation process. That means automating what you can, then reviewing it as a whole to see whether or not it makes sense and is useful. And when the documentation is “done,” analyze usage and keep improving it.

Learn how GhostDoc can help to simplify your XML Comments, produce and maintain quality help documentation.

Is XML Dying?

May 29, 2018T.J. Simmons6

Since the beginning, web developers have always needed to transport and store data, and there’s an entire generation of web developers that has only ever used JSON (JavaScript Object Notation) for that purpose. That choice makes sense; JSON is easy to read and conforms to JavaScript syntax. Some developers may not have even heard of XML (eXtensible Markup Language). XML was also designed to be both human- and machine-readable. Its purpose is primarily to handle the transportation and storage of data. And this data exchange was not meant for web only. Most importantly, distributing data of different flavors works fantastically well with XML, all because XML is designed to be highly flexible within a strict structure. Yet JSON continues to be the first choice for many developers. Which prompts the question: is XML dying??

In this article, we will explore the differences between XML and JSON. We will address which conditions best suit which format. At the end, we’ll dig into a few scenarios where XML will continue to play a crucial role in data exchange.

(more…)

9 Tips for Simplifying Your Code Documentation

May 1, 2018Peter Morlion2

Documenting your code is important. It tells other developers what the code does, why it is constructed in a certain way, and how to use it. Good documentation saves them time when they are trying to perform a certain task that isn’t straightforward. It will probably also save you time?because the human brain can only store so much information. Even your own code will confuse you at some point in the future.sp

Even though code documentation is important, many developers find it tedious. This is exacerbated by the fact that many companies associate code documentation with long Word documents that must be kept up to date manually. Not exactly developer heaven.

So how can we simplify code documentation while still keeping it effective? (more…)

VS2017 v15.6 Compatibility Releases

March 9, 2018Serge BaranovskyNo Comments

Today we have made available compatibility update releases for GhostDoc and CodeIt.Right.

This update addresses the “Visual Studio still loading the project.” message and other issues after upgrading VS2017 to the v15.6.

Products updated include –

GhostDoc v5.9 – all editions
CodeIt.Right v3.3 – all editions
GhostDoc Pro v2018 Beta

Download GhostDoc v5.9

Download GhostDoc v2018 Beta

Download CodeIt.Right v3.3

GhostDoc v2018 Beta 3 is available

January 30, 2018Serge BaranovskyNo Comments

(Mar 9, 2018)?Update: new?build v2018.0.18070 has been posted to address the VS2017 v15.6 compatibility issue.

Changes in the Beta 3, build v2018.0.18030 –

New feature – Document Project – now can generate XML Comment templates for a whole project
Added support for the <inheritdoc> tag – for type members only in the XML Comments as well as the generated help documentation. This allows using the tag instead of copying the documentation from base members and synchronizing the changes.
Visual Editor improvements
- New commands – Add Table, Remove Table
- New commands – Add Note, Remove Note
- Now the tags not recognized by the Visual Editor are added back to the XML Comment when saving the edits
- Now render the Code Contract section preview
- A number of improvements that impact proper XML comment generation
Added?/cleanup switch for the command line tool – when used will delete?all files and folders in the output directory before creating help documentation.
Support for Code Contracts when generating help documentation
Added Options -> General -> ‘Keep solution properties file in the .vs folder’ allowing to hide the solution properties file (<solution path>.GhostDoc.xml) in the solution’s .vs folder
The Cleanup checkbox in the Build Help Documentation dialog has been changed to a button. Now the folder must be cleaned up manually – this is to prevent accidental file loss when the output folder picked at an incorrect location.
Default toolbar icon is now Build Help Documentation where previously was Comment Preview

For the complete list of changes, see What?s New in GhostDoc v2018 Beta

For information on the original Beta release, please see the Visual Editing for XML Comments post.

Download GhostDoc Pro Beta

Version note

We changed the way we do the versioning for our products to keep it straightforward and simple. The new upcoming major GhostDoc version is to be v2018.x instead of the v6 we initially announced. Going forward we will name the major versions by the year of the release.

Feedback

We appreciate your feedback on the new features; please email us at support@submain.com or post in the GhostDoc Beta Forum.