Documentation Archives - Software Quality Blog

C# Comments: A Complete Guide, Including Examples

March 5, 2019Carlos SchultsNo Comments

Time for another C#-related post. We’ve already covered a fair amount of the language’s keywords, types, and concepts in previous posts. Today’s post covers comments, a topic that you might think is trivial. My mission in this post is to convince you otherwise. True, comments are far from being the most exciting programming topic you could think of, I admit. And sure, comments have gotten a negative reputation over the years. But there’s more to comments than you might think. In this post, you’ll learn about the definition of C# comments, followed by common justifications for their usage. Then we’ll…

Software Documentation: What You Need to Document and How

February 19, 2019Vlad GeorgescuNo Comments

Software documentation is all about bringing clarity into a code baseline. It provides clues to clarify the meaning of certain code structures. For this purpose, we use best programming practices and tools to clarify our software. When documenting software, we aim to minimize time spent hunting for meaning. We want anyone using or reading our code to know exactly what we meant when we wrote it. In addition, they should also know how to use our code without having to look for extra clues. Whether it’s an API, a suite of REST services, or simply a method in your code,…

How to Document Code: 5 Ways to Help Maintenance Programmers

January 22, 2019Vlad Georgescu5

Imagine you’re a software developer working on a financial application. One day you’re assigned (or, if you’re agile, you pick yourself) to implement changes to the overtime computation logic so your company can sell the application in France. In France, the official work week has 35 hours (lucky them) instead of the 40 hours in the US. Being new to the team, you’re not sure where to begin, so you start searching the codebase for the keyword “overtime.” Let’s see the search results. No, no, no, maybe, no, no, maybe. Hmmm. OK, looks like it’s in this file, and then…

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”…