Self-Documenting Code

[[deleted user]]

Overall, this book is overly wordy, and this chapter is the wordiest! I contains every aspect of comment commentary imaginable.

I started programming life as an assembly language programmer. I commented every line of code. Then came high level languages, but with variable names limited to 8 characters in some cases. My comments were pretty liberal. These days, I try to focus on making the code speak for itself, and only sprinkle in comments when I think that they are essential to go beyond the code.

I do take exception to the author's negative view of "two-phase commenting" (writing the code in one pass, commenting it in a second pass). This is the way I do things, and I find that it helps force me to review code I have written as I add the comments.

[Erik]

The "To Comment or Not to Comment" section's dialog reminded me alot of GEB dialogs. It had comments about comments and mirrors several themes in GEB. I enjoyed this section.

Yes, this chapter was long and covered more types of commenting than I could name.

I often find code comments that reference non-code documents useful. Yes, I have to look up some non-code document. My experience has been that a non-code document is more likely to be correct, preserved, and updated than sections in code. Of course, this is not true in all cases.

[Aleksander]

I like the suggestions given in previous chapters about naming variables, classes, constants, and routines, and also refactoring and many others that make a code very readable and easy to understand.

I think comments are very useful when they explain algorithms, documentation references, and code changes. I like when people put notes and dates for the code changes both in code and source control because searching source control for changes descriptions is very time consuming, at least with source control tool that we use at work.

To be honest I didn’t really expect such a long chapter on commenting to be included in this book because many code readability techniques were covered in previous chapters. I guess code readability is one of the author’s primary goals in developing software. If someone thinks this is not enough about this topic there are additional resources at the end of the chapter :)