About Comments

[דודו פאר‎]

Hi John how are you?

I'm in the middle of your book and I'm loving it!

I have some esthetics issues with the idea of heavily commenting the code, it looks ugly and distracting (I'm coming from the paradigm of clean code) what is your thoughts on the matter?

And more importantly there is no example or data on the internet about the idea of commenting as design tool, are you aware of that? Can you post examples or video session of using it as a tool?

Thanks a lot,
David Peer

[John Ousterhout]

Hi David,

A few questions/thoughts on your message:

I have some esthetics issues with the idea of heavily commenting the code, it looks ugly and distracting (I'm coming from the paradigm of clean code) what is your thoughts on the matter?

Can you say a bit more about what you see as the problem? For example, what does "ugly" mean, and why does that matter? Why would a comment be distracting, if it helps you to understand the code that follows?

And more importantly there is no example or data on the internet about the idea of commenting as design tool, are you aware of that? Can you post examples or video session of using it as a tool?

I don't recall seeing other mentions on the Internet about the idea of commenting as a design tool; it's something that I realized during my own experiences coding. I don't have any video sessions of this, or examples other than what I described in APOSD.

If anyone else on this mailing list has tried using commenting as a design tool, perhaps you can share your experiences?

-John-

[Peter Ludemann]

Before starting to write code, I like to organize my thoughts by writing an essay about what I'm going to do. It's usually a bad essay, and gets thrown away, but key parts of it become comments in my code, or extracted as a README.md file.

This essay acts as a design review, where I'm both the author and the reviewer. It's even better if I write something that's good enough for another person (or people) to read and comment on. This is especially useful if my design fits into a complex existing system, where there may be subtle limitations that I'm not aware of but that others might notice (so, it's important to have experts on the existing system as participants in the review). However, this requires that the reviewers spend significant time and effort looking at my design (a 1-hour design review meeting with half a dozen people in the room is not enough!), so I've had mixed results with design reviews. Google Docs is a good tool for such reviews because it allows people to add comments and revisions, and have offline discussions; this also helps preserve some of the reasoning behind design decisions. Writing README.md files with github-style review is another approach that can work (and updated as part of the coding process).

The "design essay" can be thought of as a lightweight version of http://wiki.c2.com/?PlanToThrowOneAway .

(As to OP's "ugly and distracting" -- a good IDE can expand/hide things like comments.)

[Jeff Lombard]

Hey All, if I had more time I would have written something more succinct! But hope my $0.02 helps!

> If anyone else on this mailing list has tried using commenting as a design tool, perhaps you can share your experiences?

Yes, it even has a name "Comment-Driven Development" - it's a bit confusing because there's two uses of this word I've come across, one is satirical humor about something that should be avoided and the other is writing out comments to aid in development. I'll speak to the latter and refer to it as CDD (Comment Driven Development).

There are two ways I've seen CDD work:

1. To reduce complexity through abstraction
2. To organize code in a pattern/templated fashion where an interface/annotation might be inappropriate.

Reducing complexity with CDD.

If you use it as an abstraction or placeholder to represent unimplemented functionality, I think it's incredibly useful. It let's you focus on high level things and without implementing the details. For example rather than implement a helper function for a task, you can instead just name a function and describe in comments what it should do. Example

I like to use looking at a map as a good analogy for this, and dealing with complexity in general. When we're dealing with complexity, our brains can only handle so much context at a time. Right? So when you're zoomed out you're only looking at major cities. Trying to to list all of the towns in this context would be unnecessary and distracting.

But when you get to the lower level implementation, that's when detail becomes more necessary. So say you're trying to figure out what cities are near Philadelphia. The high level context works well. But if you were trying to ask "What is a Philadelphia area?" you'd need a lower level context like this:

Knowing how/when to switch between contexts or "zoom levels" when dealing with complexity is, in my opinion, key to solving complex problems. With programming this can mean focusing your mental effort on a single zoom level at a time. Comments can be a tool to help with this and represent the areas of the map that we can't fully zoom in on.

The only problem I've experienced with this, is that it can lead to a procedural styling of programming unless careful.

In most cases after doing this, it makes sense to get rid of the comments. Unless the comments add more information to the 'map view' or context then they are a distraction. (example)

Organizing code in a pattern/templated fashion.

Another great way of using comments is to organize code in a templated fashion. Some people might point to something like an interface here, but interfaces only deal with behavior, not implementation.

A great example of this is the "Setup, Input, Transform, Output" paradigm. I'm surprised that I didn't find anything on that with a quick google search, but maybe it's just a nugget of industry knowledge that was handed down to me by some great mentors.

Essentially this is a pattern used in organizing code within a function:

• Setup
• Input
• Transform
• Output

Example

Hope this helps!

- Jeff

[Dvir Volk]

Redis comes to mind as an example of great code with great comments, that serve as design docs, API docs and code annotation. 

For example: 

https://github.com/antirez/redis/blob/unstable/src/rax.h

https://github.com/antirez/redis/blob/unstable/src/rax.c

The author of redis has a very good blog post about comments:

http://antirez.com/news/124

While I don't usually adhere to such stellar standards, I did the same many times and usually it helps a lot. e.g.

https://github.com/RedisLabsModules/RediSearch/blob/master/src/tag_index.h

--
You received this message because you are subscribed to the Google Groups "software-design-book" group.
To unsubscribe from this group and stop receiving emails from it, send an email to software-design-...@googlegroups.com.
To post to this group, send email to software-d...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/software-design-book/CAGXJAmxtNKrHkuxfwDNHa1N8fANVz%2B4rNQ74fiPjeCkUKuKBPg%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--

Dvir Volk Software Engineer dvi...@google.com +972-54-779-8785

[Orlando Méndez Morales]

Hi John -and group:

Below my 2nd hand anecdotal opinion.

Best wishes for 2018.

---

John Ousterhout wrote:

Well, I cannot provide  a 1st hand experience, but I remember a colleague saying that whenever he wanted to do some transformation coding (in the context of ETL tools, which might be very visual/graphical), he'd first include a note, and describe there the pseudo code for all the steps his transformation code needed to do. So, I think that's what you refer to as designing tool? I.e. you can a-priori include comments -or the graphical equivalent- to decide/guide what will you code next?

[דודו פאר‎]

hi everybody, thanks for the inputs!

john regarding your questions:

Can you say a bit more about what you see as the problem?  i think that a lot of comment can be distracting and can become a kind of mental load, 

bad example  , good example this is clojure style (from the lisp family, this is one of my prefered languages), we call it doc-string, and it is idiomatic! 

 For example, what does "ugly" mean, i think that ugly code for me is two things: 

1,  if i can't read the code in one shot from top to bottom like parts of a story and 

2. the coloring schema that make code and comments so different that in fact i see two blocks of distinct text  interleaved together. 

i think that esthetics plays a part in it. see for example how nice it is in the second link above, it looks natural!

 and why does that matter? it is important when i want to evolve and create my style of coding or the team style guide if im talking about a team.

Why would a comment be distracting, if it helps you to understand the code that follows? the comment by itself is not distracting (especially when you really need it and it can help you!)

 but in a relatively big class or function i don't like the idea of a lot of comment all over the area! and i think that there is a strong relationship between simplicity(low cognitive load) and succinctness.

thanks a lot,

David Peer  

P.S.

i found this great video on youtube that gives examples of comment driven development.  

and when i examined it a little bit i found that i'm doing this process myself, but on paper for thinking about the abstractions and the steps that are needed and so on. 

‫בתאריך יום ד׳, 26 בדצמ׳ 2018 ב-22:52 מאת ‪Orlando Méndez Morales‬‏ <‪mmo...@hotmail.com‬‏>:‬

You received this message because you are subscribed to a topic in the Google Groups "software-design-book" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/software-design-book/kIq42jPTR7U/unsubscribe.
To unsubscribe from this group and all its topics, send an email to software-design-...@googlegroups.com.

To post to this group, send email to software-d...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/software-design-book/DM5PR03MB2441A7675D543F5CD4695FD6C1B50%40DM5PR03MB2441.namprd03.prod.outlook.com.

[rj]

Does anybody want to chime in on literate programming?   I've never done it, and I know that it's typically needed editor support.

As modern "best practices" have eschewed comments, I'm increasingly seeing comments as a valuable tool.

I'm also interested in any research, products integrated into modern development systems that tie in code, design, comments in novel ways.

To view this discussion on the web visit https://groups.google.com/d/msgid/software-design-book/CAB3OcEf%2BoS2OgLQJYwCdMzWw5d2qnLV%2BcauQk5c0E%2BYzHdX33Q%40mail.gmail.com.

[Jeff Lombard]

Not sure if this is what you had in mind for literate programming, but I've used a combination of Jest/Cucumber/Webdriver on a team. We essentially had non-developers write out user stories, our automated test runner parsed them and ran automated tests against them. It was really cool in practice. It wasn't super sophisticated, but it worked.

Also tagging onto the comments thread: Look at the Kubernetes Repo (Saw on HN earlier), this is commenting to the extreme!

- Jeff

To view this discussion on the web visit https://groups.google.com/d/msgid/software-design-book/CANZdC1gL3D9P4Ukq3uw%3Dn3eLez34YVrNU0hBMFPPizZUSfo%3D8Q%40mail.gmail.com.

[John Ousterhout]

My responses interleaved below:

‪On Thu, Dec 27, 2018 at 3:52 AM ‫דודו פאר‬‎ <dudu...@gmail.com> wrote:‬

hi everybody, thanks for the inputs!

john regarding your questions:

Can you say a bit more about what you see as the problem?  i think that a lot of comment can be distracting and can become a kind of mental load, 

bad example  , good example this is clojure style (from the lisp family, this is one of my prefered languages), we call it doc-string, and it is idiomatic! 

Hmmm, I found the comments in your "good example" so vague that they didn't tell me much. In particular, they don't describe the interfaces for the functions well enough to save me from having to read the code of the functions.  I'm still not sure I understand why a comment would be distracting or introduce a mental load, if the comment is done well. I don't tend to have a lot of comments inline in code. Most of my comments are for method headers and for data structures; given these comments, the bodies of most methods are pretty easy to understand. Where there are comments inline in code, they typically come in chunks before each major section of code, providing a high-level view of what that code is doing. The goal is to make it easier to understand the code that follows, if you know the big picture about it what's trying to do. If the comment doesn't make it easier to understand the code, then the comment probably isn't needed. Is it possible that the comments you find "distracting" are really just bad comments?

 For example, what does "ugly" mean, i think that ugly code for me is two things: 

1,  if i can't read the code in one shot from top to bottom like parts of a story and

One disadvantage of comments is that they increase the vertical height of code, so you can't get as much code on your screen at a time. However, with modern screens you can show at least 50 lines at a time; I find that this is usually plenty enough context, even with some interleaved comments.

  

2. the coloring schema that make code and comments so different that in fact i see two blocks of distinct text  interleaved together. 

i think that esthetics plays a part in it. see for example how nice it is in the second link above, it looks natural!

Personally, I like having different colors for code and comments; I find that it breaks the code up into logical blocks, each starting with a comment. Of course, if you don't like different colors or fonts for comments, you can always change your IDE to make them the same. 

 and why does that matter? it is important when i want to evolve and create my style of coding or the team style guide if im talking about a team.

Why would a comment be distracting, if it helps you to understand the code that follows? the comment by itself is not distracting (especially when you really need it and it can help you!)

 but in a relatively big class or function i don't like the idea of a lot of comment all over the area! and i think that there is a strong relationship between simplicity(low cognitive load) and succinctness.

See my note above about there not usually being a lot of comments in the middle of code. As for simplicity and succintness, simplicity usually leads to succinctness, but I haven't found much causality the other way around. 

-John-

[דודו פאר‎]

Thanks for the feedback! 

בתאריך יום ו׳, 28 בדצמ׳ 2018, 04:59, מאת John Ousterhout <ous...@cs.stanford.edu>:

[Vinicius Policena]

Chapter 9 of the 2nd edition of "Code Complete: A Practical Handbook of Software Construction" contains a description of the pseudocode programming process, in which comments are used as a design tool.

[William Adams]

Mark Haniford asked:

>Does anybody want to chime in on literate programming?   I've never done it, and I know that it's typically needed editor support.

I've been working on this for a while now. Previously I used .dtx (documented .tex files) and added the docmfp package by Peter Wilson, but since have begun using a system developed w/ some help from Alan Xiang: https://tex.stackexchange.com/users/219915/alan-xiang as noted at:

https://tex.stackexchange.com/questions/722886/how-to-write-out-multiple-text-files-from-multiple-instances-of-latex-environmen

which gave me a LaTeX package:

https://github.com/WillAdams/gcodepreview/blob/main/literati.sty

which allowed me to write:

https://github.com/WillAdams/gcodepreview/blob/main/gcodepreview.tex

which compiles to:

https://github.com/WillAdams/gcodepreview/blob/main/gcodepreview.pdf

Unfortunately, both the .sty and .tex files have to be kept in synch to manage which filenames/tags will be written out as separate files, and most egregiously, it is necessary to manually track and update how many lines each block of code is.

That said, it's far better than my previous approach of having 3 separate text editor windows tiled across my monitor and trying to scroll through them to find the next bit of code which needed to be updated.

I found the principles from APoSD to be excellent guiding lights, and read through the book one chapter at a time, then revising my code in its then current state to reflect the principles which were learned before moving on to the next chapter.

If anyone wants to try the .sty file above, but has difficulty setting it up, let me know what filenames you wish to use/write to and I'll gladly work with you to make a template. (and if anyone is a LaTeX wizard skilled enough to generalize that, or automate the line numbers, I'd be very glad of any assistance which could be offered).

William

-- 

William F. Adams

Sphinx of black quartz, judge my vow.

https://designinto3d.com/