• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

Who writes Documentation in Source code?

 
Greenhorn
Posts: 19
1
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Looking at the documentation provided by source code (say it in Java source, Spring Framework etc), I am wonder how they made it.
Are they hire better documentation writers? Or it is written by Developer of that class?
ex: In org.springframework.util.Assert class


/**
* Assertion utility class that assists in validating arguments.
* Useful for identifying programmer errors early and clearly at runtime.
*
*

For example, if the contract of a public method states it does not
* allow {@code null} arguments, Assert can be used to validate that
* contract. Doing this clearly indicates a contract violation when it
* occurs and protects the class's invariants.
*
*

Typically used to validate method arguments rather than configuration
* properties, to check for cases that are usually programmer errors rather than
* configuration errors. In contrast to config initialization code, there is
* usally no point in falling back to defaults in such methods.
*
*

This class is similar to JUnit's assertion library. If an argument value is
* deemed invalid, an {@link IllegalArgumentException} is thrown (typically).
* For example:
*
* <pre class="code">
* Assert.notNull(clazz, "The class must not be null");
* Assert.isTrue(i > 0, "The value must be greater than zero");</pre>
*
* Mainly for internal use within the framework; consider Jakarta's Commons Lang
* >= 2.0 for a more comprehensive suite of assertion utilities.
*
* @author Keith Donald
* @author Juergen Hoeller
* @author Colin Sampaleanu
* @author Rob Harrop
* @since 1.1.2
*/



Did authors write this entire statement? If true. Looks like it is a tougher job than writing a class alone.

Please provide your comments.
 
Marshal
Posts: 79151
377
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Probably varies from company to company. Some places employ technical writers to improve that sort of documentation, write manuals, etc.
 
Bartender
Posts: 1210
25
Android Python PHP C++ Java Linux
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Did authors write this entire statement? If true. Looks like it is a tougher job than writing a class alone.


Developers would have written most of it as it evolved.
It's possible technical writers, testers and other developers reviewed the resulting docs and filed bugs to get things corrected or clarified later on.
Search Spring JIRA and you'll find many javadoc bugs filed there.

For some companies, even the API documentation is critical to their business. Spring is one example.
Microsoft and its MSDN was another, back in the day when Windows and its Win32 API were king.
Such companies pay attention to and invest resources into their code documentation.

Regardless of its business importance or company support, writing detailed docs is a good practice.
You don't want to find out a year later that you are unable to understand your own code
 
Karthik Shiraly
Bartender
Posts: 1210
25
Android Python PHP C++ Java Linux
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
And now a nice story:

A company I worked in was heavily process-oriented in its development practices.
After a number of releases over the years, they had acquired good skills at project estimation.
They found that giving devs the time to think, map out the skeleton of the logic in pseudocode, write code comments and review all that - all this before writing the actual logic - reduced both unit and integration bugs.
So even though these appeared to be simple tasks often ignored in estimates, these people did include them in project estimation factors.
We devs were eternally grateful! Finally a company that didn't treat thinking as goofing off
 
Saloon Keeper
Posts: 27752
196
Android Eclipse IDE Tomcat Server Redhat Java Linux
  • Likes 1
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
JavaDocs have the potential to generate a fairly complete documentation package, but this is almost never seen in actuality. Sun's JavaDocs were almost never sufficient to actually learn a technology, and were therefore augmented by external tutorials. Actually some Sun JavaDocs are outright horrible. The JavaDocs for JavaServer Faces go on at length about internal trivia while not actually specifying proper usage or what data is valid and when. Worse, they often inherit docs from a superclass and don't amend them to allow for variations in the subclass.

One place where I worked had a fairly rigorous documentation process, where before the code was actually written several formal and external documents had to exist:

1. The Executive Summary - Why the product needed to exist and (briefly) what it did. 1-2 pages max.

2. The Functional Specification - a longer, more detailed document that told what the product was supposed to do.

3. The Implementation Specification - Specifics on how the product was implemented and maintained.

Additionally, often there might be Administrator Guides, SysAdmin docs, and User Guides, as needed.

Most of that stuff was written by the developers, since, hey, it's the 21st Century so why get a professional specialist to do something when you can just dump one more task on the primary developer? Then again, I've worked with documentation specialists who couldn't seem to be persuaded that the documents needed to track the software and not simply exist for their own sakes.

One thing that I consider critical in good docs is that they indicate range and domain of the method in question. To properly use a resource, it is critical that the user knows what data may be validly fed to it and what data to expect coming out of it. For complex functions, that may include what items are optional, what items are mandatory and when, and what default values will be applied. Often an optional item has co-required optional items, so I also like to define what that set it and when it applies.

Good docs don't just tell the user how to use a product, they are a succinct reminder of what the code is actually expected to do. That can be invaluable when maintenance time comes around because it allows people to remember what the constraints are and so (hopefully) not to break things.

I was into "literate programming" even before Knuth coined the term or Java was developed. In fact, I'd developed an AWK script that auto-generated Windows Help files for code based on specially marked comments, not only in the headers (JavaDoc style), but in the function body (usually step-by-step explanations of what was being done).

In fact, if you look at sample code I've posted on the Ranch forums, you'll see that almost always I include some JavaDoc information. I figure it will help promote good behavior in others. Or at least they might get used to seeing what proper JavaDoc tag usage looks like.

One of the best incentives to use Javadoc markup is that many modern IDEs can look aside and provide "hover help" when you do a trial type-in of a method or object reference. So a good documentation header can make coding a lot easier.
 
Karthik Shiraly
Bartender
Posts: 1210
25
Android Python PHP C++ Java Linux
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Tim Holloway wrote:Most of that stuff was written by the developers, since, hey, it's the 21st Century so why get a professional specialist to do something when you can just dump one more task on the primary developer? Then again, I've worked with documentation specialists who couldn't seem to be persuaded that the documents needed to track the software and not simply exist for their own sakes.


Same here. However, I mostly enjoyed writing those specs, probably because I like writing and drawing. Sometimes, interfacing with tech writers was necessary. Some of them were good and made us think twice about what we had written or how we had expressed it, but others were just nuisances imposed by the process.

I was into "literate programming" even before Knuth coined the term or Java was developed. In fact, I'd developed an AWK script that auto-generated Windows Help files for code based on specially marked comments, not only in the headers (JavaDoc style), but in the function body (usually step-by-step explanations of what was being done).


Great idea!
My first intro to literate programming was via Python and the IPython web notebook. Used as I was to the usual IDE + external docs workflow, I was initially not impressed and kept wondering what problem it solved.
But as I used it more and more, it kind of grew on me. Now I think the notebook concept is just awesome.
When REPL comes in Java 9, hopefully IPython (now called Jupyter) will break out of its python community silo and gets used a lot more by java community.
I'd love to implement an entire enterprise CRUD web app that integrates with some external service, using nothing more than a bunch of collaborating jupyter notebooks, with all the architectural, functional and design specs drawn and explained right there above the java code that implements them, with version control . It'll probably be trivial to then extract out only the java code and compile them into binaries for production.

One of the best incentives to use Javadoc markup is that many modern IDEs can look aside and provide "hover help" when you do a trial type-in of a method or object reference. So a good documentation header can make coding a lot easier.


Excellent point. It's even more so with scripting languages, all of whom now have some variation of the javadoc concept in their toolchains. Not sure if java was the first to do so formally, but it was definitely a good idea.
Support for markdown would make it sweeter.
 
Tim Holloway
Saloon Keeper
Posts: 27752
196
Android Eclipse IDE Tomcat Server Redhat Java Linux
  • Likes 1
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Some additional things that code documenters might want to keep in mind:

1. JavaDoc has support for package documentation file. Originally, if you included a "package.html" file in the package directory, it would be integrated into the resulting docs. The convention changed somewhere around Java6/7, and I don't remember what the new version of that feature is, but it's still there.

2. You can embed HTML in your JavaDoc comments. I often put bullet lists and tables in mine. The JavaDoc live view window in the Eclipse IDE will honor it, not just the batch processor.

3. You can also leverage item #2 with additional goodness. I have one or 2 projects where I use graphviz to generate VRML or JPEG graphics and use the HTML IMG tag in my JavaDocs to pull them in.

4. Markdown language isn't currently supported by JavaDoc (although since it, too reduces to HTML, I suspect it could be made a plugin option). But if you're storing your code in a git archive, the markdown will be marked up for browsing. Github supports this, as does the github-like Gogs hosting app that you can run in-house like I do. Probably some of the other SCS's such as Subversion have MD options now as well, although I haven't checked. Note to self: see if there's a Trac plugin for their source browser for that.
 
Bartender
Posts: 10780
71
Hibernate Eclipse IDE Ubuntu
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Oh goodee, a thread about documentation - the bane of most programmers' existence. And a cow to mamidi for generating such a lively discussion.

As a programmer who "grew up" hating documentation myself, I can honestly say that it was mostly not my fault.
1. Before Java, there were very few languages that offered a proper documentation facility.
2. Most companies are incredibly (and in some cases criminally) bad at managing it - either in the abstract, or as useful additional information. Specifically:
  • They don't automate it.
  • They don't link it.
  • They don't like it.
  • Nobody wants to spend any money on it.
  • They expect it to be done by people who are not qualified; and in media that has nothing to do with where or why it's needed.
  • The procedure is often a "checklist" - ie, it's done by rote.
  • (And this is the worst) It's based on official "forms" - very often developed in-house.

  • Now things may have improved since I used to slog over scads of Word or WP docs that I knew damn well would never be read, but I suspect not.
    And the reason is that it starts at the top: If "documentation" is simply regarded as a necessary evil, or something done to appease auditors, then it will never be seen as anything more than a chore. If, on the other hand, it's a natural part of the software building process, with all the creation, refactoring and linking tools that we have for programs, then I see no reason why it shouldn't be just as enjoyable as programming.

    FYI, here are "Winston's Laws":
    1. Document what IS; not what used to be, or what you would like to have.
    2. Brevity is the soul of wit.
    3. Program documentation should be in the program.
    4. Almost all other system documentation (with the possible exception of flowcharts) should NOT be done by programmers.
    5. All documentation done in Microsoft Word (or OpenOffice Writer) is crap.
    6. Any piece of documentation that takes more than 20 minutes to read probably never will be.
    7. By the time documentation is produced it is usually already stale, so systems should:
    (a) Minimise the work involved.
    (b) Minimise the amount of time it takes to refactor.
    (c) Publicise it - ie, tell people where to find it.

    Take one simple point from that list: Instead of writing out scads of narrative in a Word document, why not do it in Powerpoint? That'll force authors to
    (a) Shorten the content.
    (b) Include ONLY what's relevant.
    (c) Think about their audience.
    and if it's done properly, you have the basis of an actual presentation or lesson that can be given to people.

    My 2¢.

    Winston
     
    Tim Holloway
    Saloon Keeper
    Posts: 27752
    196
    Android Eclipse IDE Tomcat Server Redhat Java Linux
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • Quote
    • Report post to moderator
    My condolences, Winston.

    I can understand how you feel. Once, when I was asked if I'd considered becoming a professional writer, I responded that that was too much like working for a living - I'd rather do software.

    But documentation isn't new - not even automated documentation. Done right - it's wonderful stuff. Done wrong, it's like every other steaming pile of "magic bullets" (to mix metaphors) that PHB's ever rammed down an unappreciative team's throats.

    Back even before my time, when Fred Brooks wrote his seminal work The Mythical Man-Month*, he proposed the Chief Programmer Team concept as the software analogy to a surgical team, and one of the members of a well-formed team was to be a Librarian, responsible for the project documentation. Of course, CPT never really caught on (as I've said more than once, today's model is almost the exact inverse - instead of efficient specialists, we consider it more "productive" to make one person do it all). Still, IBM has definitely been in the documentation business a long time. In addition to their infamous reams of programmer and operator manuals, the IBM program product themselves were copiously documented. IBM used automated flowcharters (a tool whose utility drastically dropped with the advent of OOP), HIPO diagrams (I have my very own HIPO stencil and pad), and a number of other tools as well. Indeed, IBM is one of several companies that led me to draw the conclusion that the more "businesslike" a software development team was, the more likely that the product in question would be overpriced garbage. Although IBM has had a reputation for stodginess, the VSAM program product had manuals that were very obviously written by people having fun, and VSAM has been one of their most reliable products.

    IBM, of course, also was big into online help, and there's no small similarity between the old TSO help file formats and modern-day Markdown Language (minus the hyperlinks). In the 1980s, they also moved their documentation (which had been almost always computer-edited) into BookManager format, providing online reader utilities. Eventually that became their present-day web-based library system.

    Unix, of course, had man pages, and since Unix had its roots in document creation, publication, and management, it, too contributed to automated system documentation. Other vendors then stole what they liked - my first exposure to computerized typesetting was a variant of the Unix "nroff" system on the Prime inicomputer I admin'ed in college.

    By about 1985, things were definitely picking up. When I got the system documentation for my shiny new Amiga developer account, the pages were generated by a software package they called auto-doc, which in turn inspired the AWK-based helpfile builder I myself designed to work off C++ source code files.

    JavaDocs appeared shortly thereafter (not my doing), and I think that more than any other system, they've cemented in place the concept that source code should carry its own technical documentation. Most language platforms now have something similar, such as the Oxygen system used for a lot of Linux programs.


    Code-extracted documentation isn't the whole story, however. In 1986 I was working on Macintosh software and outlining programs were the rage. We used them copiously, as GUI apps are especially amenable to outline-based design. Stuff like cascading menus were a natural, we had sections for each dialog, sections for the different functionalities, all sorts of outlines and sub-outlines.

    Stand-alone outliners, however, more or less vanished when products such as MS Word gained significant outlining, indexing, and hypertext capabilities. And it's what I use as the basis for my functional and implementation specs to this day, although in the very earliest stages, I may use Freemind as an idea mapper, since it's well suited to rapid entry of ideas but can also drag and drop stuff around and it gets re-organized. It also can export to RTF format so that Word (actually, LibreOffice these days) can pick it up and go on. Actually, I've also been known to use Wikis when the details get too long for a paragraph.

    So you see, I have a multi-pronged view of documentation. Plus, as I mentioned earlier, I've been doing "literate programming" since before Knuth popularized the term. First I write the comments, then I stuff code between the comments. The comments typically carry semantic markers so that automated documentation tools can assemble the essential ones into a synopsis of what the code is doing. In the mean time, I have support documents that "keep me honest" - they separate the forest from the trees so that important design considerations don't get forgotten when clever implementation details are applied.

    From the sound of it, what you've been subjected to was some sort of horrible one-size-fits-all approach to documentation where everything from top to bottom gets done in one bloated tedious document. That's abominable. As I said earlier, I have been working in environments where documents are expected to do one thing and do it well. The only documents that should require start-to-finish reading are short and succinct. The detailed stuff is in topical reference manuals, not reading materials.

    Now ideally, along with code reviews, there should be documentation reviews where before a project is fully committed, the docs are checked against the code - which not only ensures that the docs should be (reasonably) up to date, but also that the code is doing what it's expected to do. But, of course, as you've noted, nobody is ever willing to spend time and money on that. They'd much rather spend it on panic resolution and explaining ro the press why their sensitive data is in Bulgaria.

    ====
    * Brooks was obviously already aware of "silver bullets". Come to think of it, I think that's the title of one of the chapters.
    reply
      Bookmark Topic Watch Topic
    • New Topic