#begin

Hey, welcome back! Today we will dive into a really interesting topic of the book A Philosphy of Software Design. It’s about comments and why we should write them. This highly contractics the practices presented in Uncle Bob’s Clean Code which is why it’s such an interesting topic to investigate. Spoiler alert; I resonate more with Clean Code practices than Prof. Ousterhout’s. But let’s see why.

Why write comments? The four excuses.

Chapter 12 is called: Why write comments? The four excuses. And it highly contrasts or contradicts the advise in Clean code. I personally hate comments in code, there I said it. I feel most comments are just clutter and agree with Uncle bob on his statement that comments are a failure of expressing ourselves through code. But then again, in the clean code blog about comments, we also discussed the comments that are generally good or acceptable to have in code like for example; these massive legal comments at the top of files, which we simply need for legal reasons. Or comments that describe how a regular expression works, since no sensible human can read and understand regexes a week after you wrote it. Or comments that serve for documentation generation purposes. But let’s see what Prof. Ousterhout says about comments.

He starts of by saying that in-code documentation plays a crucial role in software design and that comments are essential to help developers understand a system to work efficiently. He even goes as far as saying that this in-code documentation as comments plays such an important role that, without them, you cannot hide complexity. The process of writing comments, if done correctly, will actually improve a system’s design.

And, Oh damn, I simply cannot disagree more than I already do. I’m on totally different planet here. I disagree with Prof. Ousterhout because, as Uncle Bob says, comments often lie and spread misinformation. They can be useful but they really need to be maintained properly and often, they will not be since we as programmers write code, not comments or documentation. I will even dare to say that over like, 90% of programmers despise writing documentation.

I however do agree with John when he says that good software design loses much of it’s value when it’s poorly documented. That’s totally true, but I think we have far better and more modern means of documentation like wiki’s for example. We at work, use Atlassian confluence where all technical designs, decisions, uml diagrams and everything can be found. Everything is documented there and thus we do not use comments for these purposes. And then also, I would like to point out that unit and integration tests are used a documentation as well. So given a piece of code there are unit tests that document how it aught to work. This is the best technical documentation there is in my opinion, because Tests can never, ever be out of sync with the system and they are so formal that they can execute and produce some result. So, no comments for me please.

John says that many developers think comments are a waste of time yet other see value in comments but do not know how to write them or never get around to actually writing them. To me, this just sounds as developers needing to write documentation. Why would you write such documentation as comments in source code files. I think this is such a weird practice. Why would you write such documentation in source code? What do you think about this? Please let me know if you like.

John then says that the remainder of this chapter will describe the four excuses why developers don’t write comments, and then, in the next chapter, chapter 13 he will dive a bit deeper into this subject and teach you have to actually write good comments. So let’s first dive into these four excuses and then continue with chapter 13 to see what he has to say about it.

So the four excuses to not write comments are and I quote:

1) “Good code is self-documenting.”
2) “I don’t have time to write comments.”
3) “Comments get out of date and become misleading.”
4) “The comments I have seen are all worthless; why bother?”

Haha those four reasons really sound like something I would say myself. It’s exactly what I’ve been ranting about the past couple of minutes. So let’s explore what he says about it and let’s start with the first one, Good code is self-documenting.

He says that some people believe that if code is written well it is so obvious that no comments are needed. He says this is a myth and simply not true. He does admit that you can do a lot of things to improve the understandability of your code, like choosing good names for variables, functions and classes. And I agree, I think Uncle bob would agree as well but then he says something I oppose greatly and I’ll quote him so I don’t translate it wrong: “there is still a significant amount of design information that can’t be represented in code. For example, only a small part of a class’s interface, such as the signatures of its methods, can be specified formally in the code. The informal aspects of an interface, such as a high-level description of what each method does or the meaning of its result, can only be described in comments.”

I mean, I disagree heavily here. Has he ever considered Domain Driven Design? Where you design your domain language and objects together with subject matter experts and your team. This way you can describe these informal parts perfectly like method calls, and also result objects. You don’t need comments for this. I think it would be really horrible to describe all this in comments.

He then says that sometimes you need to describe the rationale for a specific implementation in comments. And I somewhat agree with him here though. This is also something Uncle Bob would find acceptable. However, writing this in comments is no excuse for actual proper documentation in some place it actually belongs. I know most of us all hate to write documentation, but if there are things of such importance that you would write a comment documenting your rationale or this specific implementation, you might as well just document it in some technical design.

He also says you should document why and when, under which circumstances you should call a specific method. I think, you can avoid this if you have your domain model setup correctly. But I also agree with him and I’ve done this myself too. I sometimes add summaries to properties, methods and classes when I think the comment would be valuable. But I find that these cases are very very rare.

He then continues on by saying that many developers think people should read the method body if they want to know what it does and thus, methods are very short and everything is abstracted out. And thus you end up with many little functions that are really shallow. John says that this does not make code easier to read, it makes it harder to read. Since, when you need to understand some class or module you will need to read everything anyway and thus you will read all those little extracted low level functions anyway.

I disagree again. In Clean code, there is this concept that you class should follow a newspaper style of writing. Starting with abstract matters and the further you read, the more detailed things become. Uncle bob says this is polite. If you need to know what a module does, just read it until you have the information you need. And since everything is wrapped in nicely named functions you do not need to read all the internals.

He then says something really interesting which might even change your or my opinion about his view of comments. He says that comments are fundamental to abstraction. In the blog about chapter 4 we talked about that the goal of abstractions is to hide complexity. If users must read the code of a method in order to use it, then there is no abstraction. Without any comments, the only abstraction is the method declaration, which specifies its name and the names and types of its arguments and results. The declaration is missing too much essential information to provide a useful abstraction by itself.

He also gives a very nice example, which I agree with by the way, and that is for the function substring again. It has a start and end index. But there is no way to indicate whether the end index is inclusive. And yeah, I agree. This would be a nice opportunity to add a summary to a function which explain these things. Yet I still think, in many cases, maintaining a correct domain model beats any comments in code. But he’s right that for such low level functions as the substring example, you might as well add some summary to the function with those details. It’s just that these comments allow you to capture additional information that the callers need and thereby completing the simplified view while hiding implementation details.

And yeah, he’s right here that these comments can augment the details of code. But I would suggest only to add summaries, and not randomly scattered in-lined comments everywhere. These in-lined comments will clutter your code. But these summaries are generally helpful, I agree. Also, when you write proper summaries for properties, methods and classes they will show up in your IDE when calling this code. But, I also want to remind you of another piece of advise from clean code and that is to only add these summaries when they actually add valuable information. If you add for example a summary above a variable called Time that says “time”, there is no benefit and thus it is all clutter. Don’t add these summaries in a dogmatic way, add them where they make sense and add some proper information.

So that’s it for the first excuse not to write comments. And I’m still not convinced I should write any based on all this. I do agree that summaries can help in some situations but I would not call a summary, a comment. To me a comment is some random in-line or block comment that describes the code. But to John, it seems that comments serve as the main source of documentation, which I think is not a great idea. But alright, I hope this wasn’t all to negative so let’s continue on with the next excuse.

So let’s set some things straight here before we continue with the next excuse not to write comments. I think I may have been overreacting all this time. I want to make the differentiation between comments, and what we call summaries in a C# context. Summaries, are comments too in some sense. But, they will also show up in your IDE through intellisense and are used when generating documentation with something like DoxyGen. Straight up comments on the other hand are in my opinion these random in-line or block comments in code that are just there. They do not show up through intellisense, and also wont appear when generating documentation. So, summaries are kinds of comments I would say are good, and they are exactly what Prof. Ousterhous has been describing till now. However, the other random comments I would say are clutter and totally unnecessary. So I guess we found some middle ground here. What do you think about this? Please let me know. Maybe it’s just me being picky. But let’s continue with the book.

And next up is the excuse: “I don’t have time to write comments”. Haha. John says it’s tempting to prioritize comments lower than development tasks. And I agree, I definitely prefer developing over writing documentation that is read once a year, or when new recruits join the dark side. But on the other hand, we have all technical designs, with rationale, discussions and artwork in confluence, which is really helpful sometimes. I just don’t see why you would add all this to your source files… which I feel John keeps hinting at, although that’s probably not what he wants you to do. As I said before, It feels like john wants that comments should be your main source of documentation.

Prof. Ousterhout says that often, developing new features are prioritized over documenting existing features, and since most software or game project are under immense pressure to get things done on time, documentation is often a side task that never gets done. And yeah, I agree this is often the case. You should make time for documentation or else you will end up without it. He says this is part of the strategic mind, an investment mindset. If you want good software structure which will allow you to work with efficiently over the long term, you need this documentation.

And again, I totally agree. I just don’t agree with the fact that John wants you to write all this in comments and not proper documentation elsewhere. He says you should probably spend like 10% of your time writing comments. And then he says something interesting which is, and I quote: “many of the most important comments are those related to abstractions, such as the top-level documentation for classes and methods”. I agree. But these comments aught to be summaries which popup in your IDE with intellisense. If the comments to not pop up while writing code, they are not as useful as John might say they are. You might never read them then.

The next excuse not to write comments is: “Comments get out of date and become misleading”. I feel like this is coming straight from Clean Code. This is one of the most important side effects of comments as described in clean code. Uncle Bob says that comments are not maintained well and thus are out of date, spread lies about the code and mislead the reader of the code. Prof. Ousterhout says he will get back to this subject in a later chapter, chapter 16. Comments do sometimes get out of sync with the code but this does not have to be a major problem. It should not take that much time to maintain these comments. He also says that code reviews are a means of detecting and fixing stale comments.

And I agree. I’ve seen many times that during code review for pull-requests comments are pointed out. Most of the time, we delete them since we don’t want them in the code since they are old and wrong anyway. But I still agree that code reviews are a nice way of control to detect old comments and point out they should be updated or deleted.

And the last excuse to not write comments is: “All the comments I have seen are worthless”. Yup, this is something I would agree on. Just because, most comments are simply a duplicate of the code yet described in natural language instead of a formal language, like code. So I prefer reading the code, instead of the comments since the code cannot lie, but the comment can. And thus most comments are worthless. Prof. Ousterhout does not give much advise for this specific excuse. He just says that it’s not that hard to write proper documentation and he will teach you how to in the upcoming chapters. So we’ll see what he has to say about this in future chapters.

He then finishes this chapter off with some comments about the benefits of well-written comments. And I have a feeling I will agree with most of what he has to say here. He starts by saying that he hopes he changed the reader’s mind, so ours, that comments are a good thing. And Yeah, he changed my mind but only if he means summaries instead of all the kinds of random comments scattered through the source code. As I said before, summaries in C# serve a specific documentation purpose so if he means those I fully agree with him.

He says, and I quote: “The overall idea behind comments is to capture information that was in the mind of the designer but couldn’t be represented in the code”. And again, I’m not so sure. I know what he means but still, I think that technical designs and UML diagrams etc. serve this purpose as well and they are not managed within the source code. He even says the following, and I quote again: “Without documentation, future developers will have to rederive or guess at the developer’s original knowledge; this will take additional time, and there is a risk of bugs if the new developer misunderstands the original designer’s intentions. Comments are valuable even when the original designer is the one making the changes: if it has been more than a few weeks since you last worked in a piece of code, you will have forgotten many of the details of the original design.”

I agree that summaries would serve a nice purpose while developing. But I just think that all this high level documentation, design decisions and other important decision-making should be documented elsewhere than in comments. This is why we have products like wiki’s or confluence for example.

He then refers back to chapter 2 where he describes how complexity can manifest itself in software systems. There are thee, remember? There was change amplification; a seemingly simple change requires code modifications in many places. Cognitive load; in order to make a change, the developer must accumulate a large amount of information. And three, Unknown, unknowns; it is unclear to make a change and what code needs to be modified.

Prof. Ousterhout says that comments can help with the last two of these issues, so Cognitive load and unknown unknowns. He says that documentation can reduce the cognitive load by providing developers with the information they need to make changes and by making it easy for developers to ignore information that is irrelevant. And I fully agree here, note that he specifically says documentation, not comments. So I agree, documentation will reduce the cognitive load for developers. I just think that this documentation is often found in other places than massive comment blocks. And I suppose John would agree with me, and Uncle Bob as well.

He also says that, and I quote; Documentation can also reduce the unknown unknowns by clarifying the structure of the system, so that it is clear what information and code is relevant for any given change. And I agree again, especially because he says that documentation can do this, not comments specifically.

So that’s it for chapter 11 Why write comments? The four excuses. I’ve been ranting a lot this chapter and I hope you understand my opinion. I think that comments that are written as summaries have a place in code. They can provide meaningful information and can serve as documentation. But I just don’t think you should abuse these summaries and only document things this way. I think documentation in wiki’s or things like confluence makes much more sense than writing it all in comments. Since comments are only available to developers through source code. But you want this kind of documentation to be available to other stakeholders as well. You don’t want some producer or CTO even have to clone the git repo to view the documentation.

But yeah, I do agree with Prof. Ousterhout that proper summaries are often a good practice.

#end

01010010 01110101 01100010 01100101 01101110