View stunning SlideShares in full-screen with the new iOS app!Introducing SlideShare for AndroidExplore all your favorite topics in the SlideShare appGet the SlideShare app to Save for Later — even offline
View stunning SlideShares in full-screen with the new Android app!View stunning SlideShares in full-screen with the new iOS app!
Different Types of Documentations for ProgrammersA new developer might be confused about which kinds of documentationare important, because we often use the very general termdocumentation rather than specifying the type. Here’s a look at someof the types of documentation out there.Code commentsWhen documentation is mentioned amongst developers, comments inserteddirectly into the source code are probably the most commonunderstanding. This is especially true for recent graduates or newerprogrammers who encountered it in school, but never learned aboutmore rigorous forms of documentation.Comments have lost a lot of their utility over the years. Between thedevelopment of systems allowing longer, more descriptive variablenames and development platforms and systems that allow for otherkinds of documentation, comments no longer serve as the de factodocumentation solution. That said, code comments still have value.Code comments should not be used to replace descriptive variablenames, though they are excellent for explaining the logic underlyinga piece of code — not necessarily the how of a code block but thewhy. For example, a useful comment might be, “Spec says that a namemust be three characters long and have only letters” to explain apiece of validation code. Comments become more useful when theydirectly refer to the specification, a bug, or other externaldocumentation in an easy-to-reference way. “Fix for bug #598″ or“Refer to change request A991″ can go a long way in helping futuremaintainers understand the thinking behind an otherwiseincomprehensible piece of code. Writing useful comments along theselines should become a habit if it isn’t one already.“Self-documenting” codeThanks to systems that allow variable, class, and function names tobe longer than they used to be, it is much easier to write “self-documenting” code; that is to say, the names of things convey theirmeaning without the need for inline comments. For example, a function
such as “prfltocnsl” does not let the potential user know what itdoes as well as “PrintFloatToConsole.” Like using inline commentswisely, this should become a standard practice for developers.Generated API-style documentationSome languages allow you to embed detailed documentation within thesource code in a format (typically XML) that automated tools can useto generate packaged help. Some systems (like Visual Studio) can pickit up and use it in other ways too. This can be a really useful, butit is a lot of work to do something useful.How many times have you seen the documentation for a ToString()method read something like, “Produces the string representation ofthe object.” Gee, that was… uh… completely obvious, thanks. Howabout letting me know how that happens instead? For example, let’ssay you have a collection with a ToString() method. Instead offorcing the developer to guess what the output will look like, thedocumentation should provide an example of what a sample instancelooks like when ToString() is called. Likewise, too many times the“examples” just show the obvious syntax in a basic “hello world”context without explaining how or why you would really do any ofthis.Bug tracker, task list, or projectmanagement systemThere has been an explosion in tools that allow teams to enter bugs,tasks, to-do lists, and so on. The tools allow items to be trackedvery granularly, and for the user to assign gobs of metadata to anygiven item. With this metadata, managers can do things like makegraphs, charts, and reports showing a ton of different stats, likeaverage bug resolution time or the number of features implemented perdeveloper. Some of these systems can tie into your source codesystem, so that you can easily view code check-ins in the context ofthe tasks they addressed (this is a very handy feature).While the stats that can be pulled are often of dubious relevancetowards evaluating quality or productivity, these systems have lotsof value. Being able to rapidly find and mine common bugs, changerequests, and so on is a big help. It’s also nice to not have to
wade through endless piles of separate pieces of paper, emails, orfiles trying to figure out where someone stuck that change request soyou can figure out why you spent three weeks making a change thateveryone seems to hate.UMLUML is a special file format design for documenting applications. UMLcan be consumed by a variety of tools to produce documents, databasediagrams, process flowcharts, and more. Even better, some tools cantake UML and stub out applications and databases based upon it.UML is particularly prevalent in the Java ecosystem, thanks to theRational Suite of tools that IBM owns. UML seems to be considered anenterprise development tool, due to the learning curve and cost ofthe tools associated with it.Ad-hoc documentsThis style of documentation is sadly too prevalent. With ad-hocdocumentation, you usually lack version control. It’s also difficultto search and, worst of all, you tend to get multiple copies of thedocuments with differences floating all over the place.There are some uses for these kinds of files, but they work a lotbetter if they are participating in a more rigorous documentationsystem, such as attached to a bug ticket or change request.Recommend Office .NET/Silverlight Component:Spire.XLS for .NET and SilverlightSpire.Office for .NET and SilverlightSpire.Doc for .NET and SilverlightSpire.PDF for .NET