#begin

In todays blog we will take a look at chapter 15 of A Philosophy of Software Design. This chapter is going to be about a practice where you write your comments/summaries before you write any code. Sounds weird right?

Write the comments first

When I read this title I really get a TDD vibe. But this would be like Comment Driven Development or something haha. However, John does make a valid case here when he says that many developers put off writing documentation until the end of the developing process. And surely he’s right about this. Many people will put of writing this kind of detailed docs till the end because, well, you have not implemented it yet. Especially with the types of comments Prof. Ousterhout wants you to write like comments describing low level implementation details like index being inclusive or exclusive in the substring function example.

These kind of functions are extracted from the code while developing. This is a very organic process and thus you do not know exactly with what functions you will end up with. But, yes, the public interface you might add summaries before writing an actual implementation. Doing Comment Driven Development fits the same purpose as TDD has; You write the test first to make sure your code is able to pass the test, so you can prove it works, but also that you will have tests in the end. Or you might end up without tests. Comment Driven Development does the same for comments instead of tests.

Let’s see what Prof. Ousterhout will teach us about writing comments first shall we? So he says that if you write comments in the beginning of the process you are making it part of the design of the code. And I fully agree! John says it will help you produce better documentation and make the process of writing it more enjoyable. And I think I agree again. This also happens in TDD; it’s far more fun to write your test first, then make it pass and then do refactorings to fit the design, than to write your test after you made it “work” and trying to retrofit your tests to the code.

And also, to make a little segway to the two previous episodes; Prof. Ousterhout said that good comments provide precision when documenting low level concepts and provide intuition when they describe high level concepts. I think, when you comment before you code you are in a better position to write these comments since you will focus on the why and what of the function, and not on the how since the code has not even been written yet. So writing the comments first seems like something very useful to me. But let’s continue with the first section of this chapter.

The first section in this chapter is called: “Delayed comments are bad comments”. Haha, yes that sounds like some universal truth right. Many developers put off writing the comments with excuses like: ”the code is still changing” or “I don’t have time now” or “I’ll write the comments before putting my pull request up for review”. They’ll have excuses that say that they will wait with writing comments until the codebase stabilizes. But let’s face it, many developers just hate writing documentation and will put it off for as long as they can. I’m guilty of this myself too.

John says there is never a convenient moment to stop developing for some time and fill in the missing comments, and it very easy to rationalize that the best thing for the project is to move on and fix bugs or implement features. This sounds so familiar… This is the same arguments people will have when they have to write tests for existing code. That’s one of the reasons people practice TDD. If you write the test first you are sure you have the code tested, the code is testable, and it’s more fun even.

Prof. Ousterhout says that if you write comments retroactively you will end up with bad comments and it’s not fun to write. Furthermore, writing comments after the code is complete will deliver bad comments since you have checked out mentally since the code is done and you are eager to move on. You just want to comment it as quickly as possible. So you quickly comment everything to add enough so that it looks respectable.

Next John describes his process of writing comments and it goes as follows, I think it’s nice to include it in the episode, so here we go:

1) For a new class, I start by writing the class interface comment. 2) Next, I write interface comments and signatures for the most important public methods, but I leave the method bodies empty. 3) I iterate a bit over these comments until the basic structure feels about right. At this point I write declarations and comments for the most important class instance variables in the class.
4) Finally, I fill in the bodies of the methods, adding implementation comments as needed. 5) While writing method bodies, I usually discover the need for additional methods and instance variables. For each new method I write the interface comment before the body of the method; for instance variables I fill in the comment at the same time that I write the variable declaration.

This seems like a pretty reasonable practice right? This is not how I write summaries since I follow a more organic approach to design. I do think a lot about design before I create something but I’ll admit I will extract a lot of functions while writing code since I like that practice from Clean Code. But I can write a summary first on a class or interface level and then write the implementation. These comments are a bit more abstract I guess so you might as well write them in the beginning.

John also has a very nice quote here as well which is, and I quote: “When the code is done, the comments are also done. There is never a backlog of unwritten comments”. This highly correlates to TDD, I like this.

Let’s continue with the second and most important benefit of writing comments at the beginning which is that comments are a design tool so they improve the design of the software being built. Again, this sounds like a promotion for TDD, but it’s about summaries. And because I can relate it to TDD, I agree with John. Although he also says this, which I simply do not agree with in any shape or form. But John says: “Comments provide the only way to fully capture abstractions, and good abstractions are fundamental to good system design”. Comments are not the only way to capture abstractions and as I said in the previous episode; Has he ever considered Domain Driven Design!? I agree with Prof. Ousterhout that nice summaries, especially describing low level concepts are important, improve the system design and I might even say that low level summaries are fundamental to design. The substring example with inclusive or exclusive indexes comes to mind again. When that summary pops up in your IDE while typing, you don’t have to check the implementation to see what the indexes mean. So yeah, these are really really useful. How high lever summaries should not be fundamental to design since we have far better practices for such things like, as I said just a second a go, Domain Driven Design. But alright, I think I have explained this a couple of times now in the past 2 or 3 episodes so let’s continue with the book.

Next, he points out something I find really interesting and that is that comments can serve as a canary in a coal mine of complexity. John says that if a method or variable requires a long comments, it is a red flag that you don’t have a good abstraction. I mean, this sounds so darn familiar again. In TDD, if you need to write a lot of SetUp and TearDown code, just to be able to test something in isolation, your code is probably far too complex, has too many dependencies, and thus means you don’t have a good abstraction. So yeah, John is certainly right here I think. If you require long summaries to describe things, you may want to spend some time redesigning the code. If you follow the Comment Driven Development strategy, so write the comments first, redesigning the code will not take much time since, there is no implementation yet. Also, long and complicated comments are a sign that the module is shallow. The same idea applies to variables: if it takes a long comment to fully describe a variable, it’s a red flag that suggests you may not have chosen the right variable decomposition.

He then ends this section with a red flag which says, and I quote: “The comment that describes a method or variable should be simple and yet complete. If you find it difficult to write such a comment, that’s an indicator that there may be a problem with the design of the thing you are describing”.

The third and final benefit of writing comments before you write the code is that it makes writing comments more fun. And again, this also sounds very familiar from a TDD perspective! If you write the test first and then make it pass, you get this little dopamine hit when the light switches from red to green. This is one of the things about TDD I also really enjoy. It may sound stupid but it’s really true. When you first write a failing test and then make it pass it always enjoys me. John then says that when you write the comments first they are much easier to write, but also they explain things more easily since you have not considered the implementation yet. He also says that if you write your comments first, your abstraction will be more stable. That’s interesting right?
He doesn’t dive much deeper into this but it sounds really interesting. I guess what he means is that, if you write the comments first, and keep them simple, you might feel obligated to align your code with the comment and thus keep the abstractions and code simple.

He then concludes this chapter with the advise that says; if you have not tried writing the comments first, try it and stick with it until you get used to it. I think this is a great idea, which I’m gonna pick up in my daily programming regimen.

Thanks for reading and see you next time!

#end

01010010 01110101 01100010 01100101 01101110