Documentation Archives - Software Quality Blog

Where Self-Documenting Code Falls Short

August 14, 2018Sylvia Fronczak3

You’re a clean coder. You use descriptive names for everything. You’ve refactored your app into a shrine of single responsibilities. Even your slightly crazy, off-the-grid uncle can follow the code. (Hi, Uncle Joe!) The app not only documents itself, it documents life. Or does it? Are there things you might have missed? Is there subtle context you’re going to forget between now and next week? And what crazy coding gems are you going to find a few months from now when you go to add a new feature? Where does self-documenting code fall short?

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…

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…

Can We Retire the Design Document, Already?

February 13, 2018Erik DietrichNo Comments

In the interest of running a social experiment to amuse myself, I won’t do a Google search for the term design document. I could easily do this, but I won’t. Instead, I’m going to hazard a guess as to what the search would yield: a Wikipedia article and a bunch of really old web pages that use the passive voice a lot. I say this because design documents, like the singleton design pattern and systems such as Hungarian notation, were legitimately good-seeming ideas that just landed on the wrong side of history. (And like those two things, I’m sure someone will…

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…

Different tool vendors can help you automate API documentation.

How Do You Handle API Documentation?

October 17, 2017Erik Dietrich1

The subject of API documentation reveals a fascinating property of the software development industry that makes it truly unique. When you think of a product, you think of something polished and ready to ship. That’s true of software and also of the broader world in general. But only in software can you crack the product open to reveal its internals and then ship that as well, with a different purpose. When you expose an API, this is exactly what you do. Take an offering like, say, the iconic Trello. On the surface, you have a lightweight kanban utility with a…

Code documentation and code comments are different, like red and green apples.

Code Documentation and Code Comments Aren’t the Same Thing

September 26, 2017Erik Dietrich1

Often, you hear “code comments” and “code documentation” used at least somewhat interchangeably. Perhaps the idea of code documentation has a little more formalism to it, in passing. And code comments may cover a bit less ground. But still, I hear the terms serve as synonyms for one another. And I hear this in particular when it comes to the actual construct of code comments — meaning, literally, the feature of compilers and interpreters that allows you to say, “Disregard everything after these two slashes. I’m editorializing for the benefit of other humans.” “Comment your code” and “document your code”…

GhostDoc v2018 Beta 2 is available

August 21, 2017Serge BaranovskyNo Comments

In the Beta 2, build v2018.0.230, we are continuing to build out the Visual Editor features as well as improvements and fixes New menu – Open Comment Editor – (Ctrl-Shift-E) to open Visual Editing for XML Comments Visual Editor improvements New – Insert Image New – Add/Remove Hyperlink Added Visual Editing for source code samples in XML Comment New menu and VS command – Document File Header – allows to generate/update the file header without having to re-document the file Improved performance of the Document File/Type batch actions Other improvements and bug fixes For the complete list of changes, see…

When looking for the concept of Microsoft HTML Help, it can be hard to even know what to Google.

Upgrading from Microsoft HTML Help

August 1, 2017Erik DietrichNo Comments

Before I get into talking about Microsoft HTML Help or any alternatives, let me ask you something. Have you ever had the singularly frustrating experience of staring blankly at the Google homepage? You’re staring blankly because it occurs to you that you don’t even know what words to type. Maybe this happens because you’re searching for a name that muddies the waters. Someone creates a new JavaScript framework named Taylor Swift. Or perhaps it happens because you know only vaguely how to describe the concept. Try buying a replacement cotter pin if you don’t actually know the name of the thing….

.NET Code Documentation So Easy It’s an Afterthought

July 20, 2017Erik Dietrich5

Though I’ll talk today about .NET code documentation, I want to start further back than that. And by “that,” I mean further back than .NET. I realize that may date me somewhat, but please bear with me. Most things in the programming world date back further than you’d think. For a dramatic example of this, consider functional programming. All the rage today, it actually dates back to the 60s in practice and 30s in theory. Speculating about the reason for temporal myopia would go beyond the scope of this post, but understand that this tendency toward myopia does exist. With…