Documenting intent Vs knowledge

Question

It is said you should document the intent of your function or class which I agree with. However recently this line became a little bit blurred when I was wanting someone to document why this particular class is being created.

Specific example:

public class SMSException extends Exception{.....}

In the above case there is no added code, each constructor is called with super(...)

To those familiar with throwing exceptions, creating a specific exception to throw makes perfect sense. (which is why we can throw exceptions like IllegalArgumentException, NumberFormatException etc... instead of just Exception)

Documenting the intent here seems overboard as the documentation will be the same as the class it is extending... But at times it seems appropriate to document this knowledge purely so that when new developers still finding their feet come across this can understand why this is done and not just wonder why people are doing this or what the advantage of doing this is.

So the question: Is it good practise to document that bit of knowledge here or should that knowledge remain in the lectures halls, training manuals, google, colleagues, etc... ?

Answer 1

I find it good practice to add a sentence or two to document the intended usage of the exception class. For example, the documentation of java.lang.ArrayIndexOutOfBoundesException states:

Thrown to indicate that an array has been accessed with an illegal index. The index is either negative or greater than or equal to the size of the array.

Such a short explanation is quickly written and it greatly reduces the risk of your exception class being thrown inconsistently. It also helps me to write correct catch blocks for your exception class.

For the delegating constructors, it should be pretty obvious what

public SMSException(String message);

does so explicitly documenting this might not deserve the highest priority and could even lead to less readable code due to a lower signal / noise ratio.

Answer 2

I would say documenting knowledge is much more prone to change (especially if you have an urge to document it) than documenting intent. So documenting intent is more effective if comparing the two.

Here is what I mean:

When you are talking about how something is done it has two downsides:

1) It is not clear how you are doing something and so you are feeling compelled to explain it which in and of itself might be pointing you to a bigger problem.

2) When you decide to refactor how you are doing something your knowledge more often than not will become obsolete.

On the other hand.

When documenting intent there is only one downside that at times can be excused.

1) Documenting intent shows that your code is not clear about its own intention and so you are feeling compelled to explain what it is doing. There are however times when it is okay to leave comments because you just have to solve it in a weird way and explain the intent.

However if you decide to refactor it later - you are not changing your intent you are only changing how your intention gets done. Hence your comment doesn't become obsolete.

I would recommend documenting things on a high-level from an architectural point of view by drawing diagrams (draw.io is an amazing tool that you can also integrate with JIRA if you are using it in your projects).

The reason it is better to document things from a high-level perspective is because details often times get refactored and your explanation constantly needs updates and amendments.

Once the architecture is understood the rest is a lot easier to get a grasp on along with figuring out the details.

Answer 3

I think that 'SMSException' is ok as a class name, but definitely could use more explanation as to what it means. An error sending an sms? Receiving one? Parsing one with a particular format? Not receiving one when expected?