Home » Software Development » Talking Around Your Docs

About Ashley Frieze

Ashley Frieze
Software developer, stand-up comedian, musician, writer, jolly big cheer-monkey, skeptical thinker, Doctor Who fan, lover of fine sounds

Talking Around Your Docs

We don’t write comments. The code is self documenting.

The people who say that they don’t write comments are 95% of the time NOT writing self-documenting code. They’re digging a hole into which someone will fall soon.

How I was taught to comment as I go

I was taught that you must write a method by first explaining what it will do in a sort of pseudocode called PDL – program descriptive language.

E.g.

1
2
3
4
5
6
7
8
9
// make an empty list
 
// iterate through each item in the input
 
// if the item is over the threshold
 
// then add to the list
 
// return the list of items over the threshold

What you could then do is fill in the lines of code between the comments and you’d have the perfect, commented function.

Right?

NEVER DO THIS!!!

This is not commenting your code. This is writing your code twice, once in a language the computer doesn’t understand and nor does the reader.

So Code Is Just Self Explanatory..?

A lot of code should be written to explain itself, but it will largely explain what it is doing and how, it can’t really explain why.

The objective of writing documentation in code is:

  • Help the reader navigate this region of the codebase
  • Understand the semantics of interfaces and data
  • Justify any unexpected decisions

The more self-explanatory the code is, the less you need to document, though I’d still argue in favour of things like JavaDoc, which can be published alongside the bits of your code that developers use across modules, or teams.

The important bits of this are:

  • the class header – the CRC card, showing what the class is for and its major collaborators
  • public API functions – what you expect people to use

Occasionally, you might write a mini user guide in the docs. For very public APIs, e.g. the Mockito library, this is a friendly thing to do. If it’s going to be something useful that everyone needs to refer to… otherwise, it may be a waste of time.

How People Get It Wrong

Here are some things that are either valueless, or counterproductive that I’ve seen in documentation:

  • Commenting the obvious – we can read code and if the code is unreadable, then invest time in making it readable
  • Writing stuff that nobody’s going to read – boilerplate comments, who cares?
  • Saying the type/sort of things, but not why – I know it’s a string, but what does it store?
  • Describing the algorithm in detail when it could be made self-evident in code
  • Blether/filler“This method is the method that is the method” – we can see in context that the thing being described is a method/function/class/variable – assume the reader wants to get to the meat of the sentence.
  • Writing as though a book report, rather than for the built docs – it’s not an essay, it’s code. Your documentation may get compiled into HTML and published. So what’s the minimum we need to know.
  • Not using the rich documentation features – if the documentation standard provides automatic links and cross references, then use the markup to express them, rather than miss out, or do it the long way
  • Repeating yourself by saying stuff prematurely – edit the documentation as much as the code. Sometimes documentation gets a bit unstructured and ends up getting longer as a result. Clean it!
  • Typos/grammar – dno’t meak me reed unspelchcked rbubish!
  • Meaningless adherence to a documentation standard that demands the above – if the standard’s wrong, then change it! I’m looking at you Google Checkstyle config!

All of the mistakes can be down to writing to appease the gods, rather than help the reader. If you think about what’s missing from the file after your beautifully expressed code, and add that as a context to the future reader, you won’t write anything unnecessary and you WILL write things that are useful.

Published on Java Code Geeks with permission by Ashley Frieze, partner at our JCG program. See the original article here: Talking Around Your Docs

Opinions expressed by Java Code Geeks contributors are their own.

(0 rating, 0 votes)
You need to be a registered member to rate this.
2 Comments Views Tweet it!
Do you want to know how to develop your skillset to become a Java Rockstar?
Subscribe to our newsletter to start Rocking right now!
To get you started we give you our best selling eBooks for FREE!
1. JPA Mini Book
2. JVM Troubleshooting Guide
3. JUnit Tutorial for Unit Testing
4. Java Annotations Tutorial
5. Java Interview Questions
6. Spring Interview Questions
7. Android UI Design
and many more ....
I agree to the Terms and Privacy Policy

2
Leave a Reply

avatar
1 Comment threads
1 Thread replies
0 Followers
 
Most reacted comment
Hottest comment thread
2 Comment authors
Ashley FriezeJoeHx Recent comment authors

This site uses Akismet to reduce spam. Learn how your comment data is processed.

  Subscribe  
newest oldest most voted
Notify of
JoeHx
Guest

Sometimes it’s a requirement to write “boilerplate comments.” I’m looking at you, JavaDocs for simple getters and setters.

Ashley Frieze
Guest

The question to ask is what’s the benefit of JavaDoc on a getter? It’s clearly not to document the fact that it’s a getter. In a non-trivial codebase, there will be many fields/properties of objects whose purpose isn’t perfectly guessable. For example name might mean first name, full name, last name, alias… Fields probably need documenting somewhere. One of the best places to document a field is on one of it’s getter/setter methods, as there’s a chance that that documentation will be spotted as someone navigates the codebase.

But if it just says Gets the name then it’s pointless! :)