Replace Comment With Assertion

A refactoring in which you change a comment into an assertion. Described as Introduce Assertion in Martin Fowler's excellent book, Refactoring Improving The Design Of Existing Code. See www.refactoring.com for his example.

Martin Fowler's use of Introduce Assertion is better than Replace Comment With Assertion, because it applies even when there is no comment (but there should have been).

Example:

Before:

After:

Here, we could replace comment with type.

That probably isn't what you want. It allows code like

to compile and run quietly. The -1 is quietly cast to unsigned int, and then the square root is taken:

I'm going to argue that Replace Comment With Assertion is not necessarily a universal Good Thing, and in fact is not my interpretation of Martin Fowler's idea - there is a significant difference between the words "introduce" and "replace".

Sometimes, it can be difficult to assert a specific condition. The example given above seems to be a Straw Man because it is obvious that an assertion better serves the purpose in such a trivial example. For a counter-example, consider an algorithm that sorts over a list: should we Replace Comment With Assertion here, and instead of writing: /* foo is sorted */ ? Or should we attempt to write an assert to check that each element of foo is less than the previous element, and that all the elements from the original list are preserved in the sorted list etc.?

My point is that comments and assertions are tools for achieving understanding of code. Assertions have the advantage they are enforced as code and form programmable safeguards, but then also have all the disadvantages of code: expression of abstraction can be verbose and non-trivial. In the above counter-example, our assertion may even end up being more complex than the sorting code itself. Comments allow for a higher level of abstraction in attempting to convey understanding to the reader (natural language, and all the pitfalls of it) but are not in any way "enforceable" as code or by the system.

Comments have their place and so do assertions: they are not mutually exclusive concepts. Comments are not intrinsically bad. Use the right tools for the job. Sometimes, yes, it does make sense to Replace Comment With Assertion. Other times, it doesn't. I object to this page because it implies One Size Fits All, which in this case is evidently not the case.

-- Alex Judge

I think your example is problematic. If I understand correctly, you're using the example of /* foo is sorted */ in a sort function. Why would you ever do that? Presumably in a sort function, when the function returns, the collection is sorted. As for whether we should write an assertion that checks that it is in fact sorted, of course we should, but we shouldn't put it where the comment was: we should make it a unit test. In other words, the assertion that replaces a comment may not be in the same spot as the comment was.

Or are you suggesting /* foo is sorted */ as a comment in a function that acts on a sorted list? In that case, I'd still remove it, I think; I'd replace it with either a guard assertion or (better, if language permits) type-checking, such that List.sort returns a Sorted List. In general, if something is important enough to need a comment, it's probably important enough to find a way of making the comment executable.

--Marnen Laibow Koser, 17 Dec 2014

See Assertions As Comments

Category Refactoring Category Assertions

See original on c2.com