Code Documentation. That ugly thing...

Code Documentation. That ugly thing..
Manios Christos
Thessaloniki Java Meetup Group
2014-11-28

What is code documentation
 Written specifications, instructions, logic, proof of concept of source code
so it is readable by:
– Humans
– machines

Why is it important?
 A contract between callers and implementors.
 We continuously stumble upon it!
 It may be annoying.
 We argue about it!
– Σημείον αντιλεγόμενον.
– The reason of this presentation!

Opposition arguments
 Running out of time!
 Not my responsibility..
 The others do not document. Why should I do it?
 I remember what I am coding!
 We are not Google! (or Microsoft, Pivotal etc.)
 Who is going to read it?
 If I do not document, I shall be irreplaceable.

Pro documentation arguments (1)
Documentation ..
 reminds you of what you code
 Helps in IDE autocompletion functionality.
 Creates a pleasant mood to your code editor / reviewer / colleague.
 Provides proof of your code quality (run / fail) .
 Reduces time spent on helping colleagues understand your code.
– Res ipsa loquitir (the thing itself speaks)

Documentation ..
 Generates legible Javadoc output
 Reduces rage, curse “generation” and negative emotions of your code
reviewer / editor / project colleague!
 Helps project documentation writer’s work. (Who is this??)
 Helps building productive, geographically distributed teams.

Documentation ..
 Advertises your work (and consequently yourself)!
 Makes your product more competitive to other products.
 Makes your code suitable for contributing in Open Source projects.

What is Javadoc
Javadoc is the style guide, tag and image conventions we use in
documentation comments for programs written in Java.

Javadoc guidelines
The following slides contain standards, guidelines and tips from:
 Oracle Javadoc
 Google Java Code style
 Joda Time (Stephen Colebourne's notes)

Javadoc guidelines (2)
Be aware of the following:
 Write Javadoc to be read as source code
 Use standard style for Javadoc comment: /** bob */
 Define a punchy first sentence
 Define clearly the required/allowed variations across
platform/implementations.

Package documentation
Create a file named package-info.java in every package:
(Example from Android SDK)
/**
* Contains the SQLite database management classes
* that an application would use to manage its own
* private database.
* Applications use these classes to manage private
* databases.
*/
package android.system.sqlite;

Documenting classes
 The Javadoc for each class and member begins with a brief summary
fragment.
 This is a fragment—a noun phrase or verb phrase, not a complete
sentence
 It does not begin with A {@code Foo} is a..., or This method
returns...
 nor does it form a complete imperative sentence like Save the
record..
 However, the fragment is capitalized and punctuated as if it were a
complete sentence.

Documenting classes
Lets see an example:
/**
* Exposes methods to manage a SQLite database.
* 
* <p>In addition to SQLite's default <code>BINARY</code>
* collator, Android supplies
* two more, <code>LOCALIZED</code></p>
* 
*/
public class SQLiteDatabase extends SQLiteClosable {

Documenting interfaces
Same as class javadoc. Specify a brief definition :
/**
* Interface for generic CRUD operations on a repository
for a specific type.
*
* @author Oliver Gierke
* @author Eberhard Wolff
*/
@NoRepositoryBean
public interface CrudRepository<T, ID extends
Serializable> extendsRepository<T, ID> {
}
(example from spring-data-commons)

Documenting Methods
 Use a striking first sentence
 Method descriptions begin with a verb phrase.
 Use 3rd person (descriptive) not 2nd person (prescriptive).
 Use @param, @return and @throws
 Javadoc has to be present at the minimum in every public or protected
member of the class.
 Exceptions:
 Self explanatory methods (handle with caution!!).
 Overrides of supertype members.

Documenting Methods: Example 1 (bad)
 Do not forget to use standard javadoc comments
// Begins a transaction. Transactions can be nested
public void beginTransaction() {
// your code
}

Documenting Methods: Example 1 (good)
 Do not forget to use standard javadoc comments
/**
* Begins a transaction. Transactions can be nested.
*/
public void beginTransaction() {
// your code
}

 Avoid - The description below says nothing beyond what you know from reading
the method name.
 Lazy use of JAutoDoc.
(Example from Oracle Javadoc guidelines)
/**
* Sets the tool tip text.
*
* @param text
* the text of the tool tip
*/
public void setToolTipText(String text) {
// your code
}

Documenting Methods: Example 2 (Good)
(Example from Oracle Javadoc guidelines)
/**
* Registers the text to display in a tool tip.
* The text displays when the cursor lingers
* over the component.
*
* @param text the string to display. If the text is
* null, the tool tip is turned off for
* this component.
*/
public void setToolTipText(String text) {
// your code
}

 Do not forget to mention extra capabilities of the parameters.
/**
* @param zkHost The client endpoint of the zookeeper quorum
* containing the cloud state, in the form HOST:PORT.
*/
public CloudSolrServer(String zkHost) {
// SolrJ code for constructor
}
(Example from CloudSolrServer (SolrJ 4.9.0). )

Documenting Methods: Example 3 (better)
 Personal modification: Clarify parameter variations.
/**
* @param zkHost
* The client endpoint of the zookeeper quorum
* containing the cloud state, in the form HOST:PORT.
*
* <p>It can contain multiple definitions in the form of
* <code>HOST1:PORT1, HOST1:PORT2, HOST2:PORT2<code></p>
*/
public CloudSolrServer(String zkHost) {
// SolrJ code for constructor
}

Documenting Methods: Null handling
 Define null-handling for all parameters and return types
 “not null" means that null is not accepted and passing in null will
probably throw an exception , typically NullPointerException
 "may be null" means that null may be passed in. In general the
behaviour of the passed in null should be defined
 "null treated as xxx" means that a null input is equivalent to the
specified value
 "null returns xxx" means that a null input always returns the specified
value

Documenting Methods: Null handling example
/**
* Javadoc text.
*
* @param foo
* the foo parameter, not null
* @param bar
* the bar parameter, null returns null
* @return the baz content, null if not processed
*/
public String process(String foo, String bar) {
// code
}

Documenting Methods: Exceptions
 Document the following exceptions with the @throws tag:
 All checked exceptions.
 Those unchecked exceptions that the caller might reasonably want
to catch

Documenting Methods: Exceptions example
/**
* Adds a collection of documents, specifying max time before they
become committed
* @param docs the collection of documents
* @param commitWithinMs max time (in ms) before a commit will
happen
* @throws IOException If there is a low-level I/O error.
* @since solr 3.5
*/
public UpdateResponse add(Collection<SolrInputDocument> docs, int
commitWithinMs) throws SolrServerException, IOException {
// code
}

Documenting Constants: Bad
 Do not forget to document constants
 Use standard javadoc
// dial a phone number
public static final String ACTION_DIAL="android.intent.action.DIAL";

Documenting Constants: Good
 Make your user feel comfortable, even if you think that the constant is
seld explanatory
(Example from Android SDK Intent class)
/**
* Activity Action: Dial a number as specified by the data. This shows a
UI
* with the number being dialed, allowing the user to explicitly
initiate
* the call.
* 
*/
@SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
public static final String ACTION_DIAL = "android.intent.action.DIAL";

Documenting Enums
 There is no official reference for Enums
 Enums are classes, so treat them as classes!

What is a doclet
Doclet is a program which works with the Javadoc tool to generate
documentation from code written in Java. Doclets :
 Are written in Java
 format the presentation of the content.
 create the file(s) that contains the documentation.

Java standard doclet
 Comes inside JDK distribution with Javadoc tool. :
 Format for Java S.E. 1.6
 Format for Java S.E. 1.7
 If you use Maven you can invoke it using:
 mvn javadoc:javadoc

Doclava
 Custom Javadoc doclet
 Refreshed look and feel
 Search capabilities
 Embeds versioning information (example: Android SDK reference)
 Use of templating engine for user customizations.
 More information in Google Code or Atlassian Bitbucket fork
 If you use Maven you can invoke it using:
 mvn javadoc:javadoc

4. Real world examples
(of well documented projects!)

Inspired by real world projects
 This presentation would not come into life without real world examples.
 Inspired by well known commercial projects.
 Inspired by well known open source projects.

Microsoft Development Network
 Also known as MSDN
 Commercial
 BUT .NET framework has became an Open Source project!!
 More to come!!
 Fully documented with tones of examples:
 Example: C# Reference documentation
 HEEEEY !!! This is not Java !!! BUT it is a lucid example of well
documenting software projects and programming languages.

Android OS
 Open source
 Fully documented, with examples and tutorials:
 Developer Portal
 Reference documentation
 SDK Javadoc

Apache Lucene / Solr
 Open source index / search engine
 Project sites:
 http://lucene.apache.org/
 http://lucene.apache.org/solr/
 SolrJ client reference: http://lucene.apache.org/solr/4_10_0/solr-
solrj/

Spring Framework
 Open source Java framework
 Fully documented: See http://spring.io/projects

5. One step forward:
Project documentation

Moving forward: Project documentation
 Code documentation is not a replacement of project documentation.
 Javadoc may have links to project documentation.
 Every project should be documented.
 Written and updated by documentation writers (Bazinga!)
 Collaboration between developers and writers.
 Use documentation tools (not MS Word files).
 Use source control for documentation (Git, SVN, Mercurial)

Documentation tools
Well known documentation tools:
 Markdown
 AsciiDoc
 reStructuredText
 Confluence

Markdown
 text-to-HTML conversion tool for web writers
 Markdown allows you to:
 write using an easy-to-read
 write easy-to-write plain text format
 then convert it to structurally valid XHTML (or HTML).Markdown
 Examples:
 Github pages
 Facebook osquery wiki

AsciiDoctor
 Asciidoctor is a fast text processor and publishing toolchain for converting
AsciiDoc content to HTML5, DocBook 5 (or 4.5) and other formats.
 Characteristics:
 Open source project
 Easier than XML based DocBook
 Example: Spring Data Solr Documentation

reStructuredText
 an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax
and parser system
 Easy to convert and export to other formats
 file format for textual data used primarily in the Python community for
technical documentation.
 used primarly in Sphinx documentation tool
 Example projects:
 Python documentation
 MongoDB docs
 Varnish cache docs

Confluence
 Commercial team collaboration software
 Used in corporate environments not only for documentation
 Free for Open Source Projects
 Example projects:
 Apache Foundation Wiki

Conclusion
 Do not hesitate to document your code.
 Establish a documentation strategy in your project / team / company.
 Use successful projects as examples.
 Let your good work speak for you.

Code Documentation. That ugly thing...

Recommended

More Related Content

What's hot (16)

Similar to Code Documentation. That ugly thing... (20)

Recently uploaded (20)

Code Documentation. That ugly thing...