# Best/favorite practices for commenting and documentation?

**URL:** <https://talk.observablehq.com/t/best-favorite-practices-for-commenting-and-documentation/7413>\
**Category:** Help\
**Created:** [December 12, 2022, 2:40pm UTC](https://talk.observablehq.com/t/best-favorite-practices-for-commenting-and-documentation/7413 "2022-12-12T14:40:25Z")\
**Posts on this page:** 6\
**Page:** 1

<div class="post-metadata">

**Author:** ![PhilipMathieu](https://yyz2.discourse-cdn.com/flex030/user_avatar/talk.observablehq.com/philipmathieu/32/6981_2.png) [@PhilipMathieu](https://talk.observablehq.com/u/PhilipMathieu)\
**Post date:** [December 12, 2022, 2:40pm UTC](https://talk.observablehq.com/t/best-favorite-practices-for-commenting-and-documentation/7413/1 "2022-12-12T14:40:25Z")

</div>

Hi Observable Community,

I’ve been working on a fairly complex group project in a grad school class that uses Observable. We’re in finals period now and thinking about how to best document our code, both for our own future use and for any students that pick up where we left off in future iterations of the class.

What strategies do you use for code documentation? Do you rely on commenting within the code? Has anyone had success using any of the recently-added collaboration features for the purpose of documentation?

---

<div class="post-metadata">

**Author:** ![jwoLondon](https://yyz2.discourse-cdn.com/flex030/user_avatar/talk.observablehq.com/jwolondon/32/259_2.png) [@jwoLondon](https://talk.observablehq.com/u/jwoLondon)\
**Post date:** [December 12, 2022, 6:26pm UTC](https://talk.observablehq.com/t/best-favorite-practices-for-commenting-and-documentation/7413/2 "2022-12-12T18:26:23Z")

</div>

I’m a big fan of [literate programming](https://en.wikipedia.org/wiki/Literate_programming) as a way of documenting code. Rather than embed comments in code, code is embedded in ‘comments’. Observable, and other notebook environments are natural places to do this, as text and embedded code are so easy to create.

Not only does (good) literate programming help others to read and maintain your code more easily, the act of forcing yourself to explain your code often results in you writing better code in the first place. I like to think of writing and explaining code as part of the same integrated process.

For an example, see my solution to today’s [Advent of Code](https://adventofcode.com/2022/day/12) puzzle: [Advent of Code: 2022 Day 12 / Jo Wood | Observable](https://observablehq.com/@jwolondon/advent-of-code-2022-day-12)

---

<div class="post-metadata">

**Author:** ![PhilipMathieu](https://yyz2.discourse-cdn.com/flex030/user_avatar/talk.observablehq.com/philipmathieu/32/6981_2.png) [@PhilipMathieu](https://talk.observablehq.com/u/PhilipMathieu)\
**Post date:** [December 12, 2022, 8:20pm UTC](https://talk.observablehq.com/t/best-favorite-practices-for-commenting-and-documentation/7413/3 "2022-12-12T20:20:57Z")

</div>

Thanks for the great answer. I had somehow never heard that term, though I’ve seen millions of examples of literate programming in action. I think this approach could work particularly well in situations like ours where the “product” is a separate website that embeds notebook cells — consequently, adding additional Markdown to the notebook doesn’t impact the functionality (although it might cause a nominally slower load time).

---

<div class="post-metadata">

**Author:** ![Martien](https://yyz2.discourse-cdn.com/flex030/user_avatar/talk.observablehq.com/martien/32/470_2.png) [@Martien](https://talk.observablehq.com/u/Martien)\
**Post date:** [December 22, 2022, 9:21am UTC](https://talk.observablehq.com/t/best-favorite-practices-for-commenting-and-documentation/7413/4 "2022-12-22T09:21:20Z")

</div>

Fully agree. I do have a wish for Observable, though. I want to have the code and its explanation stick together, so I can move them around as a single unit. That’s why at times I put comment in the code cell itself, rather than in a markup cell above or below.

---

<div class="post-metadata">

**Author:** ![PhilipMathieu](https://yyz2.discourse-cdn.com/flex030/user_avatar/talk.observablehq.com/philipmathieu/32/6981_2.png) [@PhilipMathieu](https://talk.observablehq.com/u/PhilipMathieu)\
**Post date:** [December 22, 2022, 2:12pm UTC](https://talk.observablehq.com/t/best-favorite-practices-for-commenting-and-documentation/7413/5 "2022-12-22T14:12:46Z")

</div>

That is a great point. More generally, it would be great if there were a way to chain one cell to an adjacent cell for the purposes of reordering.

Barring that, I suppose you could `yield` a Markdown literal or something like that…

---

<div class="post-metadata">

**Author:** ![mootari](https://yyz2.discourse-cdn.com/flex030/user_avatar/talk.observablehq.com/mootari/32/581_2.png) [@mootari](https://talk.observablehq.com/u/mootari)\
**Post date:** [December 22, 2022, 3:41pm UTC](https://talk.observablehq.com/t/best-favorite-practices-for-commenting-and-documentation/7413/6 "2022-12-22T15:41:52Z")

</div>

> [@PhilipMathieu](#):
>
> it would be great if there were a way to chain one cell to an adjacent cell for the purposes of reordering.

You can reorder groups of cells by selecting multiple adjacent cells and then moving them via option-up / option-down. Reordering via the minimap has also been added recently, which should make it easier to keep track of where your cells end up.